How to fix Option 'skipLibCheck' does not work with 'declaration' in TypeScript

TypeScriptINTERMEDIATEMEDIUM

This TypeScript error occurs when you try to use both skipLibCheck and declaration compiler options together. skipLibCheck skips type checking of declaration files, but declaration requires checking library types to generate accurate .d.ts files. The fix involves choosing one option or using alternative approaches for faster builds.

What this error means

TypeScript's `skipLibCheck` and `declaration` options have a fundamental conflict: **skipLibCheck: true** - Skips type checking of all declaration files (*.d.ts) from node_modules - Speeds up compilation by ignoring library type errors - Useful when you trust library types or need faster builds **declaration: true** - Generates .d.ts declaration files from your TypeScript source - Requires TypeScript to fully analyze and check library types - Essential for publishing TypeScript libraries The conflict arises because: 1. When generating declarations (`declaration: true`), TypeScript needs to understand the complete type system 2. This includes checking library declaration files to ensure your generated .d.ts files are type-safe 3. `skipLibCheck: true` prevents this necessary checking, creating a contradiction TypeScript enforces this restriction to prevent generating incorrect or unsafe declaration files that could break downstream consumers of your library.

How to fix "Option 'skipLibCheck' does not work with 'declaration'"

1Choose your primary goal: speed or declaration generation

First, decide what's more important for your project:

- Need declaration files (publishing a library): Remove skipLibCheck or set it to false
- Need faster builds (development/testing): Remove declaration or set it to false

Update your tsconfig.json accordingly:

For declaration generation (library publishing):

json

{
  "compilerOptions": {
    "declaration": true,
    "skipLibCheck": false  // Required for accurate .d.ts generation
  }
}

For faster builds (development):

json

{
  "compilerOptions": {
    "declaration": false,
    "skipLibCheck": true  // Speeds up compilation
  }
}

2Use separate tsconfig files for different scenarios

Create multiple TypeScript configs for different purposes:

tsconfig.json (development, fast):

json

{
  "compilerOptions": {
    "skipLibCheck": true,
    "declaration": false
  }
}

tsconfig.build.json (production/library):

json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "skipLibCheck": false,
    "declaration": true,
    "outDir": "./dist"
  }
}

Then use them appropriately:

bash

# Fast development builds
npx tsc

# Production/library builds with declarations
npx tsc --project tsconfig.build.json

3Check for inherited configs and overrides

If your tsconfig extends another config, check what options it sets:

json

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "declaration": true  // May conflict with skipLibCheck in base
  }
}

Check the base config:

bash

cat tsconfig.base.json | grep -A5 '"skipLibCheck"'

If the base has skipLibCheck: true, explicitly override it:

json

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "skipLibCheck": false,  // Override inherited value
    "declaration": true
  }
}

4For monorepos, configure per-package

In a monorepo with multiple packages, each package may need different settings:

Library package (needs declarations):

json

// packages/my-library/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "skipLibCheck": false,
    "declaration": true,
    "outDir": "./dist"
  }
}

App package (development speed):

json

// apps/my-app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "skipLibCheck": true,
    "declaration": false,
    "outDir": "./build"
  }
}

Ensure your build scripts reference the correct configs:

bash

# Build library with declarations
cd packages/my-library && tsc --project tsconfig.json

# Build app without declarations
cd apps/my-app && tsc --project tsconfig.json

5Consider alternative performance optimizations

If you need both speed and declarations, try these alternatives:

1. Use incremental compilation:

json

{
  "compilerOptions": {
    "incremental": true,
    "declaration": true,
    "skipLibCheck": false
  }
}

2. Enable declarationMap instead of full rechecks:

json

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "skipLibCheck": false
  }
}

3. Use project references for large codebases:

json

{
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/utils" }
  ],
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "skipLibCheck": false
  }
}

4. Run type checking separately from building:

bash

# Type check (can use skipLibCheck)
npx tsc --noEmit --skipLibCheck

# Build with declarations (no skipLibCheck)
npx tsc --declaration

6Verify the fix by testing compilation

Test your updated configuration:

bash

# If you removed skipLibCheck for declarations
npx tsc --declaration

# If you removed declaration for speed
npx tsc --skipLibCheck

# For separate config approach
npx tsc --project tsconfig.build.json

Check that:
- No TS5054 error appears
- Declaration files are generated (if declaration: true)
- Build completes successfully
- Output files are correct

For libraries, test the generated declarations:

bash

# Check if .d.ts files exist
ls -la dist/*.d.ts

# Test type checking with the generated declarations
npx tsc --noEmit --project test-consumer/

How to fix Option 'skipLibCheck' does not work with 'declaration' in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "Option 'skipLibCheck' does not work with 'declaration'"

Advanced notes

Related errors

Official resources & further reading