This error occurs when your React project uses a TypeScript version that is incompatible with your React configuration or build tools. Common triggers include outdated TypeScript versions, mismatched @types/react packages, or incompatible React TypeScript configurations in tools like Create React App or Next.js.
The "Your version of TypeScript is not supported" error appears when your React development environment detects an incompatible TypeScript version. This typically happens because: 1. **Build tool constraints**: Tools like Create React App (CRA), Next.js, or Vite have specific TypeScript version requirements. When you install a TypeScript version outside their supported range, they reject it to prevent runtime issues. 2. **Type definition mismatches**: The @types/react and @types/react-dom packages must align with both your React version and TypeScript version. Using older @types packages with newer TypeScript can cause type errors that tools interpret as incompatibility. 3. **Compiler feature requirements**: Newer React features (like JSX transform changes in React 17+, concurrent features in React 18) require specific TypeScript compiler options or minimum versions. When your TypeScript is too old, it cannot parse or type-check these features correctly. 4. **Configuration conflicts**: Your tsconfig.json settings might conflict with the requirements of your React build tool. For example, using "jsx": "react-jsx" with an older TypeScript version that doesn't support the new JSX transform. The error is a protective measure—React tooling prevents you from using a TypeScript version that would produce incorrect type checking or fail to compile newer React syntax.
First, verify which TypeScript version you're using:
# Check locally installed version
npx tsc --version
# Check globally installed version (if any)
tsc --version
# Check package.json version
npm list typescript
# or
yarn list --pattern typescriptNote the exact version number (e.g., 4.9.5, 5.0.0).
Install a compatible TypeScript version based on your React setup:
For Create React App with react-scripts@5+:
npm install --save-dev typescript@^4.1
# or for latest compatible version
npm install --save-dev typescript@latestFor Next.js 13+:
npm install --save-dev typescript@^5.0General React projects (React 18+):
npm install --save-dev typescript@^4.9After updating, delete your lock file and reinstall:
rm -rf node_modules package-lock.json
npm installEnsure your type definitions match your React and TypeScript versions:
# For React 18 with TypeScript 4.9+
npm install --save-dev @types/react@^18 @types/react-dom@^18
# For React 17 with TypeScript 4.1+
npm install --save-dev @types/react@^17 @types/react-dom@^17
# Check for version conflicts
npm ls @types/react @types/react-domIf you see multiple versions, deduplicate them:
npm dedupe
# or
npx yarn-deduplicateUpdate your tsconfig.json with React-compatible settings:
{
"compilerOptions": {
"target": "es5",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"strict": true,
"forceConsistentCasingInFileNames": true,
"noFallthroughCasesInSwitch": true,
"module": "esnext",
"moduleResolution": "node",
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "react-jsx" // For React 17+, use "react-jsx" not "react"
},
"include": ["src"]
}Key settings:
- "jsx": "react-jsx" for React 17+ with automatic JSX runtime
- "lib": ["dom", "dom.iterable", "esnext"] for React DOM APIs
- "skipLibCheck": true to ignore type definition conflicts temporarily
Clear all caches that might be holding onto old TypeScript configurations:
# Clear TypeScript cache
rm -rf node_modules/.cache/tsc
rm -rf .tscache
# For Create React App
rm -rf node_modules/.cache/babel-loader
# For Next.js
rm -rf .next
# For general projects
rm -rf node_modules/.cache
# Restart your development server completely
# Kill any running processes and start freshThen restart your development server:
npm start
# or
yarn start
# or
next devIn monorepos or projects with nested dependencies, force a single TypeScript version:
For Yarn (package.json):
{
"resolutions": {
"typescript": "5.0.0",
"@types/react": "18.0.0",
"@types/react-dom": "18.0.0"
}
}For npm (package.json):
{
"overrides": {
"typescript": "5.0.0",
"@types/react": "18.0.0",
"@types/react-dom": "18.0.0"
}
}For pnpm (pnpm-workspace.yaml):
pnpm:
overrides:
typescript: 5.0.0
'@types/react': 18.0.0
'@types/react-dom': 18.0.0After adding resolutions, reinstall dependencies.
Check your build tool's TypeScript requirements:
Create React App:
# Check react-scripts version
npm list react-scripts
# CRA 5+ requires TypeScript 4.1+
# If stuck on older CRA, consider migrating or ejectingNext.js:
# Check Next.js version
npm list next
# Next.js 13+ works best with TypeScript 5+
# Next.js 12 works with TypeScript 4.6+Vite:
# Vite typically supports latest TypeScript
# But check @vitejs/plugin-react requirements
npm list @vitejs/plugin-reactIf your build tool is too old, consider updating it or checking its documentation for TypeScript compatibility matrix.
Create React App Specific: CRA has strict TypeScript version requirements. [email protected] (released 2021) requires TypeScript 4.1+. If you cannot update TypeScript due to other dependencies, you may need to downgrade react-scripts or eject from CRA to customize the TypeScript configuration.
Next.js and App Router: Next.js 13+ with the App Router uses newer TypeScript features for React Server Components. Ensure you have TypeScript 5.0+ and configure "jsx": "preserve" in tsconfig.json for server components.
Global vs Local TypeScript: Avoid global TypeScript installations (npm install -g typescript) when working with React projects. They can conflict with project-local versions. Use npx tsc to always run the local version.
TypeScript Beta/RC Versions: Avoid TypeScript beta or release candidate versions in production React projects. Stick to stable releases that your build tools explicitly support.
Migration Paths: When upgrading from very old TypeScript (e.g., 3.x to 5.x), do it incrementally: update TypeScript, fix type errors, update @types packages, then update React if needed. Use the TypeScript upgrade tool (npx tsc --init --upgrade) to update tsconfig.json settings.
CI/CD Considerations: Ensure your CI environment uses the same TypeScript version as local development. Specify exact versions in package.json (e.g., "typescript": "5.0.0") rather than ranges to prevent version drift.
React Hook useCallback has a missing dependency: 'variable'. Either include it or remove the dependency array react-hooks/exhaustive-deps
React Hook useCallback has a missing dependency
Cannot use private fields in class components without TS support
Cannot use private fields in class components without TS support
Cannot destructure property 'xxx' of 'undefined'
Cannot destructure property of undefined when accessing props
useNavigate() may be used only in the context of a <Router> component.
useNavigate() may be used only in the context of a Router component
Cannot find module or its corresponding type declarations
How to fix "Cannot find module or type declarations" in Vite