How to fix Cannot use 'outFile' with project references in TypeScript

TypeScriptINTERMEDIATEMEDIUM

This TypeScript compiler error occurs when you try to use the `outFile` compiler option in a project that uses project references. The `outFile` option bundles all output into a single file, which conflicts with the incremental compilation model of project references that requires separate output files for each module.

What this error means

The "Cannot use 'outFile' with project references" error happens because TypeScript's project references feature and the `outFile` compiler option are fundamentally incompatible design choices. Project references enable incremental compilation across multiple TypeScript projects, where each project can be built independently and referenced by other projects. This requires each project to output separate module files that can be individually tracked and cached. The `outFile` option, on the other hand, bundles all TypeScript output into a single concatenated file (either JavaScript or declaration file). This bundling approach breaks the incremental compilation model because: 1. It combines outputs from multiple modules into one file 2. It prevents TypeScript from tracking which specific modules have changed 3. It interferes with the dependency graph that project references rely on When you enable both features, TypeScript detects this conflict and throws this error to prevent unpredictable build behavior.

How to fix "Cannot use 'outFile' with project references"

1Remove the outFile option from your tsconfig.json

Open your project's tsconfig.json file and remove or comment out the outFile compiler option:

json

{
  "compilerOptions": {
    // Remove or comment out this line:
    // "outFile": "./dist/bundle.js",

    // Keep other options...
    "target": "es2020",
    "module": "commonjs",
    "declaration": true
  }
}

If you're using project references, you'll need to switch to a different output strategy that supports separate module files.

2Switch to outDir for multi-file output

Replace outFile with outDir to output separate files:

json

{
  "compilerOptions": {
    "outDir": "./dist",
    "target": "es2020",
    "module": "commonjs",
    "declaration": true
  }
}

This allows TypeScript to output individual files for each module, which is compatible with project references.

3Use a bundler for single-file output if needed

If you need a single bundled file for deployment, use a separate bundler like Webpack, Rollup, or esbuild:

1. Keep TypeScript configuration with outDir for development
2. Add a bundler configuration (webpack.config.js, rollup.config.js, etc.)
3. Bundle as a separate build step after TypeScript compilation

Example webpack.config.js:

javascript

const path = require('path');

module.exports = {
  entry: './dist/index.js', // Compiled TypeScript output
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'bundle')
  }
};

4Verify project reference configuration

Ensure your project references are properly configured. Each referenced project must have composite: true and declaration: true:

json

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

Run tsc --build to rebuild all projects with the new configuration.

5Test the build process

After making these changes, test your build process:

bash

# Clean previous builds
rm -rf dist

# Build all projects
tsc --build

# Or build a specific project
tsc --build tsconfig.json

Verify that:
1. The error no longer appears
2. Each project outputs to its own dist directory
3. Project references work correctly between projects

How to fix Cannot use 'outFile' with project references in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "Cannot use 'outFile' with project references"

Advanced notes

Related errors

Official resources & further reading