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

TypeScriptINTERMEDIATEMEDIUM

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 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.

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.

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading