This error appears when attempting to combine --build and --watch flags incorrectly with the TypeScript compiler. In TypeScript 3.0+, these flags should be used as 'tsc -b --watch' (or 'tsc --build --watch') for project references, not as separate conflicting options.
The error 'Cannot use --build with --watch' typically occurs in older versions of TypeScript (pre-3.0) or when the flags are passed incorrectly. The --build flag (or -b) is TypeScript's build mode for compiling projects with project references, which allows you to structure your codebase into smaller, composable projects. The --watch flag enables continuous compilation on file changes. In TypeScript 3.0 and later, these flags can be combined as 'tsc -b --watch' to enable incremental builds with file watching for project references. However, if you try to use them as mutually exclusive options or in the wrong order with older tooling, TypeScript will reject the combination. The modern recommended approach is to use them together: 'tsc -b --watch' for development workflows with composite projects.
Verify you're using TypeScript 3.0 or later, which supports combining --build and --watch:
tsc --versionIf you're on an older version, upgrade TypeScript:
npm install -D typescript@latest
# or
yarn add -D typescript@latest
# or
pnpm add -D typescript@latestTypeScript 3.0+ allows you to use both flags together for project references.
Combine the flags properly by using -b (build mode) followed by --watch:
tsc -b --watch
# or equivalently
tsc --build --watchUpdate your package.json scripts:
{
"scripts": {
"dev": "tsc -b --watch",
"build": "tsc -b"
}
}This starts the compiler in build mode with incremental compilation and file watching enabled.
Ensure your tsconfig.json is set up correctly for project references if you're using --build mode:
{
"compilerOptions": {
"composite": true,
"incremental": true,
"outDir": "./dist"
},
"references": [
{ "path": "../shared" },
{ "path": "../utils" }
]
}The composite: true flag enables project references. For the root tsconfig.json that coordinates multiple projects:
{
"files": [],
"references": [
{ "path": "./packages/core" },
{ "path": "./packages/ui" }
]
}If you're using tsc-watch or similar wrappers, these may conflict with --build mode. For project references, use the native 'tsc -b --watch' instead:
# ❌ Don't use with project references
tsc-watch --build
# ✓ Use native TypeScript build mode
tsc -b --watchIf you need custom hooks (like running tests after compilation), consider using npm-run-all or concurrently:
{
"scripts": {
"dev": "npm-run-all --parallel dev:*",
"dev:tsc": "tsc -b --watch",
"dev:tests": "jest --watch"
}
}If you don't need project references (no composite projects), use regular tsc with --watch:
# For single projects without references
tsc --watchUpdate package.json:
{
"scripts": {
"dev": "tsc --watch",
"build": "tsc"
}
}The --build flag is only necessary when working with project references and composite projects.
Project References Deep Dive: TypeScript project references (introduced in 3.0) enable you to split large codebases into smaller, independently buildable projects. The --build flag activates a special compilation mode that understands dependency graphs between projects. When combined with --watch, TypeScript monitors all referenced projects and rebuilds only what changed. Incremental Builds: The --build flag automatically enables incremental compilation using .tsbuildinfo files, which dramatically speeds up rebuild times by tracking what has changed since the last build. Monorepo Considerations: In monorepos (using Lerna, Nx, Turborepo, or pnpm workspaces), 'tsc -b --watch' is the recommended approach for development. Configure a root tsconfig.json that references all packages, then run 'tsc -b --watch' from the root to watch all packages simultaneously. Performance Tips: For large projects with many references, --watch mode can be resource-intensive. Use the --verbose flag to see which projects are rebuilding and consider using --listFilesOnly to debug configuration issues. Alternative Workflows: Some developers prefer using bundlers (Vite, esbuild, webpack) for watch mode instead of tsc, as they often provide faster feedback loops. However, 'tsc -b' is still valuable for type checking in CI/CD pipelines.
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