How to fix Incremental builds require 'incremental' or 'composite' option in TypeScript

Add or update the 'incremental' option in your tsconfig.json file:

{
  "compilerOptions": {
    "incremental": true,
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

This tells TypeScript to save build information to .tsbuildinfo files for faster subsequent compilations. The cache file will be created in your output directory (specified by outDir).

If you're using TypeScript project references, enable the 'composite' option:

{
  "compilerOptions": {
    "composite": true,
    "incremental": true,
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "references": [
    { "path": "../shared" },
    { "path": "../utils" }
  ]
}

The 'composite' option automatically enables incremental builds and is required for project references to work correctly. Composite mode enables proper build ordering between projects and cross-project type checking.

After updating your configuration, clean any existing build artifacts and rebuild:

# Delete existing build artifacts
rm -rf dist build
rm -f *.tsbuildinfo

# Rebuild with clean cache
npx tsc --build --clean
npx tsc --build

# Alternative: Use force flag
npx tsc --build --force

This ensures TypeScript starts fresh with the new configuration and generates proper .tsbuildinfo files.

For better control over build artifacts, specify where .tsbuildinfo files should be stored:

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./.cache/.tsbuildinfo",
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist"
  }
}

This keeps build metadata separate from your source code and output directories. Consider adding .tsbuildinfo to .gitignore to avoid merge conflicts.

Ensure you're using a compatible TypeScript version (3.4 or later for incremental builds):

# Check TypeScript version
npx tsc --version

# Update if needed
npm install typescript@latest --save-dev

# Check installed version
npm list typescript

Incremental builds were introduced in TypeScript 3.4. Some features may require newer versions for optimal performance. TypeScript 4.0+ offers improved cache invalidation and performance.

If using build tools like webpack, vite, or esbuild, ensure they're configured correctly:

Webpack with ts-loader:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /.tsx?$/,
        use: {
          loader: 'ts-loader',
          options: {
            configFile: 'tsconfig.json'
          }
        }
      }
    ]
  }
};

Vite with TypeScript:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  esbuild: {
    tsconfigRaw: {
      compilerOptions: {
        incremental: true
      }
    }
  }
});

Ensure your tsconfig.json has 'incremental': true and the build tool can read it.