How to fix Option 'allowJs' is not compatible with 'checkJs' when 'declaration' is enabled in TypeScript

TypeScriptBEGINNERMEDIUMUpdated Dec 8, 2025· 118 views

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.

Quick fix

Fixes TS6307

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "declaration": true
  }
}
  1. Enable allowJs when using checkJs
  2. Verify your tsconfig.json structure
  3. Check configuration inheritance with extends
  4. Rebuild your project
typescript — error
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "declaration": true
  }
}
Option 'allowJs' is not compatible with 'checkJs' when 'declaration' is enabled

What this error means

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.

Typical symptoms

  • TypeScript compilation fails with error TS6307
  • Build process halts when running tsc or npm run build
  • IDE shows red squiggle in tsconfig.json file
  • Configuration validation fails in TypeScript CLI tools
  • Error message mentions 'allowJs' and 'checkJs' incompatibility

Common causes

  1. Using checkJs: true with allowJs: false in the same tsconfig.json
  2. Enabling declaration: true while attempting to use conflicting allowJs settings
  3. Mixing incompatible compiler flags without understanding their interactions
  4. Configuration inherited from extends that conflicts with overrides
  5. Attempting to enable one option while explicitly disabling a required companion option

How to fix "Option 'allowJs' is not compatible with 'checkJs' when 'declaration' is enabled"

1Enable allowJs when using checkJs

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:

json
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "declaration": true
  }
}

Both options must be present together when using checkJs to avoid this error.

2Verify your tsconfig.json structure

Check your tsconfig.json file to ensure you haven't set conflicting values. Here's a complete example with all related options:

json
{
  "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.

3Check configuration inheritance with extends

If your tsconfig.json uses extends, the parent configuration might be setting conflicting values. Check the extended configuration file and resolve any conflicts:

json
{
  "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:

bash
npx tsc --showConfig -p tsconfig.json

This shows the final resolved configuration after all extends are merged.

4Rebuild your project

Once you've corrected your tsconfig.json configuration, clear any cache and rebuild:

bash
# Remove build artifacts
rm -rf dist build .tsbuildinfo

# Rebuild with correct configuration
npm run build
# or
npx tsc

This ensures TypeScript recompiles with the new configuration settings.

Advanced notes

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.

Frequently asked questions

What does "TS6307" mean?
json file. 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.
How do I fix "TS6307"?
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.
What causes "TS6307"?
Using checkJs: true with allowJs: false in the same tsconfig.json Enabling declaration: true while attempting to use conflicting allowJs settings Mixing incompatible compiler flags without understanding their interactions
Is the "TS6307" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading