How to fix Cannot use --build with --watch in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 9, 2025· 110 views

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.

Quick fix

Fixes Cannot use --build with --watch

tsc --version
  1. Check TypeScript version
  2. Use correct flag syntax: 'tsc -b --watch'
  3. Configure project references in tsconfig.json
  4. Remove conflicting third-party watch tools
typescript — error
tsc --version
Cannot use --build with --watch

What this error means

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.

Typical symptoms

  • Build command fails with 'Cannot use --build with --watch' error message
  • TypeScript compiler exits immediately without compiling
  • Watch mode does not start when --build flag is present
  • CI/CD pipeline fails when trying to use both flags
  • Package.json scripts with both flags throw errors

Common causes

  1. Using an outdated version of TypeScript (prior to 3.0)
  2. Passing --build and --watch as separate, conflicting arguments
  3. Using incompatible third-party tooling that doesn't support combined flags
  4. Incorrect flag syntax in package.json scripts or build commands
  5. Using tsc-watch or similar wrappers that conflict with --build mode
  6. Misconfigured tsconfig.json preventing proper project reference setup

How to fix "Cannot use --build with --watch"

1Check TypeScript version

Verify you're using TypeScript 3.0 or later, which supports combining --build and --watch:

bash
tsc --version

If you're on an older version, upgrade TypeScript:

bash
npm install -D typescript@latest
# or
yarn add -D typescript@latest
# or
pnpm add -D typescript@latest

TypeScript 3.0+ allows you to use both flags together for project references.

2Use correct flag syntax: 'tsc -b --watch'

Combine the flags properly by using -b (build mode) followed by --watch:

bash
tsc -b --watch
# or equivalently
tsc --build --watch

Update your package.json scripts:

json
{
  "scripts": {
    "dev": "tsc -b --watch",
    "build": "tsc -b"
  }
}

This starts the compiler in build mode with incremental compilation and file watching enabled.

3Configure project references in tsconfig.json

Ensure your tsconfig.json is set up correctly for project references if you're using --build mode:

json
{
  "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:

json
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" }
  ]
}
4Remove conflicting third-party watch tools

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:

bash
# ❌ Don't use with project references
tsc-watch --build

# ✓ Use native TypeScript build mode
tsc -b --watch

If you need custom hooks (like running tests after compilation), consider using npm-run-all or concurrently:

json
{
  "scripts": {
    "dev": "npm-run-all --parallel dev:*",
    "dev:tsc": "tsc -b --watch",
    "dev:tests": "jest --watch"
  }
}
5Use separate commands if not using project references

If you don't need project references (no composite projects), use regular tsc with --watch:

bash
# For single projects without references
tsc --watch

Update package.json:

json
{
  "scripts": {
    "dev": "tsc --watch",
    "build": "tsc"
  }
}

The --build flag is only necessary when working with project references and composite projects.

Advanced notes

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.

Frequently asked questions

What does "Cannot use --build with --watch" mean?
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.
How do I fix "Cannot use --build with --watch"?
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.
What causes "Cannot use --build with --watch"?
Using an outdated version of TypeScript (prior to 3.0) Passing --build and --watch as separate, conflicting arguments Using incompatible third-party tooling that doesn't support combined flags
Is the "Cannot use --build with --watch" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading