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.
Fixes ts-node: TypeScript version mismatch
# Check global TypeScript version
tsc --version
# Check local TypeScript version (from node_modules)
npx tsc --version
# Check ts-node version
npx ts-node --version# Check global TypeScript versiontsc --version# Check local TypeScript version (from node_modules)npx tsc --version# Check ts-node versionnpx ts-node --versionts-node: TypeScript version mismatch
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.
First, identify the conflicting versions:
# Check global TypeScript version
tsc --version
# Check local TypeScript version (from node_modules)
npx tsc --version
# Check ts-node version
npx ts-node --versionNote the versions. The error typically shows something like:
ts-node v10.9.2
ts-node is using TypeScript v5.3.3 but your project uses v5.4.5Make sure TypeScript is installed locally in your project:
# Install TypeScript locally (if not already)
npm install --save-dev typescript
# Or with yarn
yarn add --dev typescriptVerify it's in your package.json:
{
"devDependencies": {
"typescript": "^5.4.5"
}
}Important: Avoid global TypeScript installations when using ts-node locally:
# Uninstall global TypeScript if causing conflicts
npm uninstall -g typescriptClear node_modules and reinstall to resolve version conflicts:
# Remove node_modules and lock files
rm -rf node_modules package-lock.json yarn.lock
# Reinstall dependencies
npm install
# Or with yarn
yarn installFor monorepos or complex setups:
# Clear all node_modules in workspace
find . -name "node_modules" -type d -prune -exec rm -rf {} ;
# Reinstall
npm installCreate or update ts-node configuration:
Option A: tsconfig.json with ts-node settings
{
"ts-node": {
"transpileOnly": true,
"compilerOptions": {
"module": "commonjs"
}
},
"compilerOptions": {
// Your TypeScript compiler options
}
}Option B: Use ts-node with --compiler option
npx ts-node --compiler typescript index.tsOption C: Environment variable
TS_NODE_COMPILER=typescript npx ts-node index.tsOption D: Use ts-node/register in code
require('ts-node/register');
// Now require your TypeScript filesIf you have multiple TypeScript installations, specify the exact path:
# 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:
const tsNode = require('ts-node');
tsNode.register({
compiler: require.resolve('typescript')
});Test that ts-node now works correctly:
# 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 versionIf successful, run your actual application:
npx ts-node index.ts
# or
npm start### Understanding ts-node's TypeScript Resolution
ts-node resolves TypeScript in this order:
1. --compiler flag or TS_NODE_COMPILER environment variable
2. compiler option in tsconfig.json's ts-node section
3. TypeScript from ts-node's own node_modules
4. TypeScript from your project's node_modules
### Monorepo Considerations
In monorepos (Yarn workspaces, npm workspaces, Lerna):
- Each package should have its own TypeScript dependency
- Use nohoist in Yarn to prevent hoisting conflicts:
{
"workspaces": {
"packages": ["packages/*"],
"nohoist": ["**/typescript", "**/ts-node"]
}
}- Consider using tsc --build instead of ts-node for complex monorepos
### Docker and CI/CD Environments
In containerized environments:
- Ensure TypeScript and ts-node are in the same layer
- Clear npm cache during build:
RUN npm ci --cache /tmp/empty-cache- Use specific version pins to avoid drift
### Alternative: Use tsx or esbuild-runner
If ts-node version conflicts persist, consider alternatives:
# tsx - faster TypeScript execution
npm install --save-dev tsx
npx tsx index.ts
# esbuild-runner - very fast
npm install --save-dev esbuild-runner
npx esr index.ts### Debugging Version Conflicts
Enable ts-node debugging:
TS_NODE_DEBUG=true npx ts-node index.tsThis shows detailed resolution information including which TypeScript version is being used.