TypeScript compiler error that occurs when using an incompatible combination of allowJs, checkJs, and declaration compiler options. This happens when these options conflict in your tsconfig.json file and need to be properly configured together.
This error occurs when you attempt to use an incompatible combination of TypeScript compiler options in your tsconfig.json file. Specifically, the `allowJs` option (which allows TypeScript to process JavaScript files), the `checkJs` option (which enables type checking for JavaScript files), and the `declaration` option (which generates .d.ts type declaration files) have restrictions on how they can be used together. TypeScript enforces these constraints to prevent ambiguous compilation behavior and ensure that the compiler can correctly handle type checking and declaration generation. The error prevents you from combining options in ways that would create confusing or invalid compilation scenarios.
When you set checkJs: true in your tsconfig.json, you must also ensure allowJs: true. The checkJs option requires allowJs to be enabled because it needs to process JavaScript files to type-check them.
Update your tsconfig.json:
{
"compilerOptions": {
"allowJs": true,
"checkJs": true,
"declaration": true
}
}Both options must be present together when using checkJs to avoid this error.
Check your tsconfig.json file to ensure you haven't set conflicting values. Here's a complete example with all related options:
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"allowJs": true, // Required for checkJs
"checkJs": true, // Checks JS files for errors
"declaration": true, // Generate .d.ts type declaration files
"declarationMap": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}Ensure that you don't have any explicit "allowJs": false or "checkJs": false that would conflict.
If your tsconfig.json uses extends, the parent configuration might be setting conflicting values. Check the extended configuration file and resolve any conflicts:
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"allowJs": true,
"checkJs": true,
"declaration": true
}
}Make sure the base configuration doesn't set checkJs without allowJs, or vice versa. You can verify what's inherited by running:
npx tsc --showConfig -p tsconfig.jsonThis shows the final resolved configuration after all extends are merged.
Once you've corrected your tsconfig.json configuration, clear any cache and rebuild:
# Remove build artifacts
rm -rf dist build .tsbuildinfo
# Rebuild with correct configuration
npm run build
# or
npx tscThis ensures TypeScript recompiles with the new configuration settings.
Understanding the Option Interactions: The allowJs option tells TypeScript to process JavaScript files during compilation. The checkJs option enables type checking within those JavaScript files (equivalent to adding // @ts-check at the top of each file). When you want to generate declaration files from JavaScript using declaration: true, these options must be configured consistently.
Declaration Files from JavaScript: One valid use case is generating .d.ts declaration files from JavaScript source code. This requires allowJs: true, checkJs: true, and declaration: true all set together. This is useful when building libraries where you want to provide type information for JavaScript source.
Migration Scenario: This configuration is particularly useful when migrating a JavaScript project to TypeScript. You can enable type checking on existing JavaScript files while gradually converting them to TypeScript, all while generating declaration files for external consumers.
File-Level Override: If you need to disable checking for specific JavaScript files, you can add // @ts-nocheck at the top of individual .js files instead of changing the global configuration. This is more flexible than modifying compiler options.
Compiler Option Dependencies: TypeScript has several options with implicit dependencies:
- checkJs requires allowJs
- declaration requires emitDeclarationOnly or compatible settings
- declarationMap requires declaration
- strict enables multiple strict checks
Always verify that dependent options are properly configured together.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript