Complete fix for TypeScript ESM import issue - recommend tsx over ts-node/esm

Co-authored-by: kobenguyent <7845001+kobenguyent@users.noreply.github.com>

Author: Copilot

docs/typescript.md

@@ -92,27 +92,33 @@ Scenario('successful login', ({ I }) => {
 - 🚀 **Works with Mocha:** Uses CommonJS hooks that Mocha understands
 - ✅ **Complete:** Handles all TypeScript features (enums, decorators, etc.)
 
-### Using ts-node/esm (Alternative)
+### Using ts-node/esm (Not Recommended)
 
-If you prefer ts-node:
+> ⚠️ **Note:** `ts-node/esm` has significant limitations with module resolution and doesn't work well with modern ESM TypeScript projects. **We strongly recommend using `tsx` instead.** The information below is provided for reference only.
+
+`ts-node/esm` has several issues:
+- Doesn't support `"type": "module"` in package.json
+- Doesn't resolve extensionless imports or `.js` imports to `.ts` files
+- Requires explicit `.ts` extensions in imports, which isn't standard TypeScript practice
+- Less reliable than `tsx` for ESM scenarios
+
+**If you still want to use ts-node/esm:**
 
-**Installation:**
 ```bash
 npm install --save-dev ts-node
 ```
 
-**Configuration:**
 ```typescript
 // codecept.conf.ts
 export const config = {
   tests: './**/*_test.ts',
-  require: ['ts-node/esm'],  // ← Use ts-node ESM loader
+  require: ['ts-node/esm'],
   helpers: { /* ... */ }
 }
 ```
 
-**Required tsconfig.json:**
 ```json
+// tsconfig.json
 {
   "compilerOptions": {
     "module": "ESNext",
@@ -126,33 +132,12 @@ export const config = {
 }
 ```
 
-**Required package.json:**
-```json
-{
-  "name": "your-project",
-  "version": "1.0.0"
-  // ⚠️ DO NOT include "type": "module" when using ts-node/esm
-  // ts-node/esm works with CommonJS-style loading
-}
-```
-
-**⚠️ Important Notes:**
-
-1. **Do not use `"type": "module"`** in your package.json when using `ts-node/esm`. The ts-node/esm loader uses CommonJS-style module loading internally and is incompatible with `"type": "module"`.
-
-2. **Use `.js` extensions in imports**: When writing TypeScript code for ESM, you must use `.js` extensions in your imports, even when importing TypeScript files:
-
-```typescript
-// ❌ Wrong - will cause "Cannot find module" error
-import loginPage from "./pages/Login"
-
-// ✅ Correct - use .js extension
-import loginPage from "./pages/Login.js"
-```
-
-TypeScript will automatically resolve `.js` imports to `.ts` files during type-checking. This is the standard approach for ESM + TypeScript projects as documented in the [TypeScript handbook](https://www.typescriptlang.org/docs/handbook/modules/theory.html#typescript-imitates-the-hosts-module-resolution-but-with-types).
+**Critical Limitations:**
+- ❌ Cannot use `"type": "module"` in package.json
+- ❌ Import statements must match the actual file (no automatic resolution)
+- ❌ Module resolution doesn't work like standard TypeScript/Node.js ESM
 
-3. **For `"type": "module"` projects, use `tsx` instead**: If you need `"type": "module"` in your package.json, use `tsx/cjs` which is designed to work in both CommonJS and ESM contexts.
+**Recommendation:** Use `tsx/cjs` instead for a better experience.
 
 ### Full TypeScript Features in Tests
 

lib/utils/loaderCheck.js

@@ -65,9 +65,18 @@ CodeceptJS 4.x uses ES Modules (ESM) and requires a loader to run TypeScript tes
     ✅ Complete: Handles all TypeScript features
 
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│ Option 2: ts-node/esm (Alternative - Established, Requires Config)         │
+│ Option 2: ts-node/esm (Not Recommended - Has Module Resolution Issues)     │
 └─────────────────────────────────────────────────────────────────────────────┘
 
+  ⚠️  ts-node/esm has significant limitations and is not recommended:
+      - Doesn't work with "type": "module" in package.json
+      - Module resolution doesn't work like standard TypeScript ESM
+      - Import statements must use explicit file paths
+  
+  We strongly recommend using tsx/cjs instead.
+  
+  If you still want to use ts-node/esm:
+
   Installation:
     npm install --save-dev ts-node
 
@@ -88,18 +97,7 @@ CodeceptJS 4.x uses ES Modules (ESM) and requires a loader to run TypeScript tes
          }
        }
 
-    3. In package.json, DO NOT include "type": "module"
-       ts-node/esm is incompatible with "type": "module"
-       
-       If you need "type": "module", use tsx/cjs instead.
-
-  ⚠️  Important: When using ESM with TypeScript, use .js extensions in imports:
-      
-      ❌ Wrong:   import loginPage from "./pages/Login"
-      ✅ Correct: import loginPage from "./pages/Login.js"
-      
-      TypeScript will resolve .js imports to .ts files during type-checking.
-      This is the recommended approach for ESM + TypeScript projects.
+    3. Do NOT use "type": "module" in package.json
 
 📚 Documentation: https://codecept.io/typescript
 

test/data/typescript-esm-imports/package.json

@@ -6,6 +6,6 @@ export const config: CodeceptJS.MainConfig = {
       require: "../helper.js"
     }
   },
-  name: "typescript-esm-imports-test",
-  require: ["ts-node/esm"]
+  name: "typescript-tsx-esm-test",
+  require: ["tsx/cjs"]
 };

test/data/typescript-esm-imports/typescript_esm_test.ts

@@ -0,0 +1,8 @@
+{
+  "name": "typescript-tsx-esm",
+  "version": "1.0.0",
+  "type": "module",
+  "devDependencies": {
+    "tsx": "^4.20.6"
+  }
+}

…/typescript-esm-imports/codecept.conf.ts …data/typescript-tsx-esm/codecept.conf.tstest/data/typescript-esm-imports/codecept.conf.ts renamed to test/data/typescript-tsx-esm/codecept.conf.ts test/data/typescript-esm-imports/codecept.conf.ts renamed to test/data/typescript-tsx-esm/codecept.conf.ts

@@ -3,8 +3,8 @@
     "target": "es2022",
     "lib": ["es2022", "DOM"],
     "esModuleInterop": true,
-    "module": "nodenext",
-    "moduleResolution": "nodenext",
+    "module": "esnext",
+    "moduleResolution": "node",
     "strictNullChecks": false,
     "types": ["codeceptjs", "node"],
     "declaration": true,

test/data/typescript-tsx-esm/package.json

@@ -0,0 +1,13 @@
+// With tsx, you can import without extension - tsx handles resolution
+import loginPage from "./pages/Login";
+
+Feature("TypeScript tsx ESM with type:module");
+
+Scenario("Import page object without extension using tsx", () => {
+  loginPage.login("testuser");
+});
+
+Scenario("Page object methods work correctly", () => {
+  loginPage.login("admin");
+  loginPage.logout();
+});