outDir and rootDir in Composite Projects
What you'll learn: Why composite projects require explicit outDir configuration and how rootDir affects the structure of your generated declaration files.
The Essential Rule
When you enable composite: true in your tsconfig.json, TypeScript requires you to explicitly specify an outDir. This isn't optional—it's a hard requirement. Why? Because composite projects are designed to be referenced by other projects, and TypeScript needs to know exactly where to find the compiled JavaScript and declaration files.
Understanding outDir in Composites
Think of outDir as the "delivery address" for your compiled code. In a composite project, other projects will reference your build outputs, so that address must be crystal clear and consistent. Without an explicit outDir, TypeScript can't reliably establish the project dependency graph.
{
"compilerOptions": {
"composite": true,
"outDir": "./dist" // Required!
}
}
If you omit outDir with composite: true, TypeScript will give you a compile error.
How rootDir Shapes Declaration Files
The rootDir setting determines the root folder of your source files and directly affects how TypeScript mirrors your source structure in the output. This is crucial for declaration files because other projects need to import from predictable paths.
When rootDir is set explicitly, TypeScript preserves your folder structure relative to that root. Without it, TypeScript infers the common root of all input files, which can lead to unexpected nesting in your output directory.
{
"compilerOptions": {
"composite": true,
"rootDir": "./src",
"outDir": "./dist"
}
}
With this configuration, a file at src/utils/helpers.ts compiles to dist/utils/helpers.js and dist/utils/helpers.d.ts. Other projects can import using the same relative path structure.
Why This Matters for Project References
When Project B references Project A, it needs to locate Project A's declaration files. The combination of outDir and rootDir ensures that the declaration file structure is predictable and matches the source structure, making cross-project imports reliable.
Key Takeaway: Composite projects require explicit outDir so TypeScript can reliably locate build outputs, while rootDir ensures your declaration files mirror your source structure for predictable cross-project imports.