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.
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.
Open your project's tsconfig.json file and remove or comment out the outFile compiler option:
{
"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.
Replace outFile with outDir to output separate files:
{
"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.
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:
const path = require('path');
module.exports = {
entry: './dist/index.js', // Compiled TypeScript output
output: {
filename: 'bundle.js',
path: path.resolve(__dirname, 'bundle')
}
};Ensure your project references are properly configured. Each referenced project must have composite: true and declaration: true:
{
"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.
After making these changes, test your build process:
# Clean previous builds
rm -rf dist
# Build all projects
tsc --build
# Or build a specific project
tsc --build tsconfig.jsonVerify that:
1. The error no longer appears
2. Each project outputs to its own dist directory
3. Project references work correctly between projects
## 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
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript