Resolving "Unknown file extension .ts" Error in Node.js

The "Unknown file extension '.ts'" error occurs when Node.js doesn't recognize TypeScript files while using ES modules. This common issue typically arises when your project configuration conflicts with how Node.js handles module resolution.

Problem Analysis

The error message appears when:

• Using "type": "module" in package.json
• Running TypeScript files directly with ts-node
• Node.js encounters .ts files but doesn't know how to process them

Recommended Solutions

Solution 1: Use tsx (Recommended for 2024)

Modern Approach

For new projects, consider using tsx instead of ts-node as it provides better ESM support and performance.

npm install --save-dev tsx

Update your package.json scripts:

{
  "scripts": {
    "dev": "tsx watch src/App.ts",
    "start": "tsx src/App.ts"
  }
}

Solution 2: Configure ts-node for ESM

If you prefer to keep using ts-node, configure it properly for ES modules:

1. Update tsconfig.json:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ESNext",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  },
  "ts-node": {
    "esm": true,
    "experimentalSpecifierResolution": "node"
  }
}

2. Use the --esm flag:

{
  "scripts": {
    "start": "ts-node --esm src/App.ts"
  }
}

Solution 3: Use Node.js Loader Directly

Run your TypeScript files with Node.js' experimental loader:

node --loader ts-node/esm src/App.ts

Or update your package.json:

{
  "scripts": {
    "start": "node --loader ts-node/esm src/App.ts"
  }
}

Solution 4: CommonJS Alternative

If you don't specifically need ES modules, switch to CommonJS:

1. Remove from package.json:

{
  // Remove this line:
  // "type": "module"
}

2. Update tsconfig.json:

{
  "compilerOptions": {
    "module": "CommonJS",
    "moduleResolution": "node"
  }
}

Advanced Configuration

For complex projects using nodemon, create a nodemon.json:

{
  "watch": ["src"],
  "ext": "ts",
  "exec": "ts-node --esm ./src/App.ts"
}

Package.json configuration:

{
  "scripts": {
    "dev": "nodemon"
  }
}

Node.js Version Considerations

Version Compatibility

Some Node.js versions (particularly v18) have known issues with ts-node and ESM. Consider:

• Using Node.js 16.x or 20.x for better stability
• Testing your configuration across different Node versions

```bash
# Check your Node.js version
node --version

# Use nvm to switch versions if needed
nvm install 16
nvm use 16

Troubleshooting Tips

1. Clear cache: Sometimes clearing ts-node cache helps:

ts-node --cache false src/App.ts

2. Check file extensions: Ensure imports include file extensions:

// Instead of:
import { module } from './module'

// Use:
import { module } from './module.js'

3. Verify TypeScript version: Ensure compatibility between TypeScript and ts-node versions.

When to Consider Alternatives

If you continue experiencing issues, consider these alternatives:

• Bun.sh: Offers built-in TypeScript support
• Vite-node: Faster development server with hot reload
• Native compilation: Compile to JavaScript first, then run

Conclusion

The "Unknown file extension '.ts'" error typically stems from mismatched module systems between Node.js, TypeScript, and your project configuration. For most modern projects, using tsx provides the simplest solution with excellent ESM support. For existing ts-node projects, ensure proper configuration with the esm flag and experimental specifier resolution.

Remember to test your configuration in your deployment environment (like Heroku) as local development might have different behavior.