How to fix ts-node: TypeScript version mismatch in TypeScript

TypeScriptINTERMEDIATEMEDIUM

This error occurs when the TypeScript version used by ts-node doesn't match the version in your project's dependencies. The mismatch prevents ts-node from properly compiling and executing TypeScript code, requiring version alignment or configuration adjustments.

What this error means

ts-node is a TypeScript execution engine that compiles and runs TypeScript code directly without pre-compilation. It requires access to the TypeScript compiler (tsc) to transform TypeScript into JavaScript at runtime. The "TypeScript version mismatch" error happens when ts-node detects that the TypeScript version it's using internally differs from the version specified in your project's `package.json` or `node_modules`. This mismatch can cause: - Incompatible TypeScript language features - Different compiler behavior - Missing or mismatched type definitions - Compilation failures ts-node performs this version check to ensure consistent behavior between development (ts-node) and production (tsc compilation). The error typically appears when you have multiple TypeScript installations or when global and local TypeScript versions conflict.

How to fix "ts-node: TypeScript version mismatch"

1Check your TypeScript versions

First, identify the conflicting versions:

bash

# Check global TypeScript version
tsc --version

# Check local TypeScript version (from node_modules)
npx tsc --version

# Check ts-node version
npx ts-node --version

Note the versions. The error typically shows something like:

bash

ts-node v10.9.2
ts-node is using TypeScript v5.3.3 but your project uses v5.4.5

2Ensure TypeScript is a local dependency

Make sure TypeScript is installed locally in your project:

bash

# Install TypeScript locally (if not already)
npm install --save-dev typescript

# Or with yarn
yarn add --dev typescript

Verify it's in your package.json:

json

{
  "devDependencies": {
    "typescript": "^5.4.5"
  }
}

Important: Avoid global TypeScript installations when using ts-node locally:

bash

# Uninstall global TypeScript if causing conflicts
npm uninstall -g typescript

3Reinstall dependencies to fix version conflicts

Clear node_modules and reinstall to resolve version conflicts:

bash

# Remove node_modules and lock files
rm -rf node_modules package-lock.json yarn.lock

# Reinstall dependencies
npm install

# Or with yarn
yarn install

For monorepos or complex setups:

bash

# Clear all node_modules in workspace
find . -name "node_modules" -type d -prune -exec rm -rf {} ;

# Reinstall
npm install

4Configure ts-node to use project TypeScript

Create or update ts-node configuration:

Option A: tsconfig.json with ts-node settings

json

{
  "ts-node": {
    "transpileOnly": true,
    "compilerOptions": {
      "module": "commonjs"
    }
  },
  "compilerOptions": {
    // Your TypeScript compiler options
  }
}

Option B: Use ts-node with --compiler option

bash

npx ts-node --compiler typescript index.ts

Option C: Environment variable

bash

TS_NODE_COMPILER=typescript npx ts-node index.ts

Option D: Use ts-node/register in code

javascript

require('ts-node/register');
// Now require your TypeScript files

5Use ts-node with explicit TypeScript path

If you have multiple TypeScript installations, specify the exact path:

bash

# Using npx with explicit path
npx ts-node --compiler ./node_modules/typescript/lib/tsc.js index.ts

# Or in package.json script
{
  "scripts": {
    "start": "ts-node --compiler ./node_modules/typescript/lib/tsc.js index.ts"
  }
}

For programmatic usage:

javascript

const tsNode = require('ts-node');
tsNode.register({
  compiler: require.resolve('typescript')
});

6Verify the fix

Test that ts-node now works correctly:

bash

# Create a simple test file
echo 'console.log("TypeScript version:", require("typescript").version)' > test.ts

# Run with ts-node
npx ts-node test.ts

# Should output your local TypeScript version

If successful, run your actual application:

bash

npx ts-node index.ts
# or
npm start

How to fix ts-node: TypeScript version mismatch in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "ts-node: TypeScript version mismatch"

Advanced notes

Related errors

Official resources & further reading