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

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 113 views

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.

Quick fix

Fixes Cannot use 'outFile' with project references

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

    // Keep other options...
    "target": "es2020",
    "module": "commonjs",
    "declaration": true
  }
}
  1. Remove the outFile option from your tsconfig.json
  2. Switch to outDir for multi-file output
  3. Use a bundler for single-file output if needed
  4. Verify project reference configuration
typescript — error
{
  "compilerOptions": {
    // Remove or comment out this line:
    // "outFile": "./dist/bundle.js",
    // Keep other options...
    "target": "es2020",
    "module": "commonjs",
    "declaration": true
  }
}
Cannot use 'outFile' with project references

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.

Typical symptoms

  • TypeScript compiler (tsc) fails with error TS5053: "Cannot use 'outFile' with project references"
  • Build process stops when trying to compile a project with both project references and outFile enabled
  • CI/CD pipelines fail during TypeScript compilation step
  • Project that previously compiled successfully starts failing after adding project references

Common causes

  1. Adding project references to a TypeScript configuration that already uses the `outFile` compiler option
  2. Enabling the `outFile` option in a TypeScript project that already uses project references
  3. Migrating from a single-file output strategy to a multi-project architecture without updating compiler options
  4. Copying tsconfig.json settings from another project without understanding the incompatibility

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

Advanced notes

## Technical Background

The incompatibility between outFile and project references stems from TypeScript's incremental compilation system:

1. Incremental Compilation: Project references use TypeScript's incremental compiler API, which requires:
 - Separate output files per module for change tracking
 - Clear dependency boundaries between projects
 - Ability to skip unchanged projects during rebuilds

2. outFile Limitations: The outFile option:
 - Concatenates all modules into one file, breaking module boundaries
 - Makes it impossible to determine which specific module changed
 - Prevents incremental compilation across project boundaries

3. Workarounds for Legacy Systems:
 If you absolutely need single-file output in a project reference setup:
 - Use tsc to compile to outDir first
 - Then use a simple concatenation script or tool to merge files
 - Consider this a deployment step, not a compilation step

4. Performance Considerations:
 - Project references with outDir enable faster incremental builds
 - outFile requires full recompilation on any change
 - Large projects benefit significantly from the project references approach

## Related Configuration Options

- composite: Required for project references, enables incremental builds
- declaration: Required for project references, generates .d.ts files
- declarationMap: Optional, generates source maps for declarations
- incremental: Can be used with project references for faster builds

Frequently asked questions

What does "Cannot use 'outFile' with project references" mean?
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.
How do I fix "Cannot use 'outFile' with project references"?
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 causes "Cannot use 'outFile' with project references"?
Adding project references to a TypeScript configuration that already uses the outFile compiler option Enabling the outFile option in a TypeScript project that already uses project references Migrating from a single-file output strategy to a multi-project architecture without updating compiler options
Is the "Cannot use 'outFile' with project references" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading