tsc --build vs tsc --project

Question

I have a monorepo where I am converting a subproject to TypeScript. In my npm scripts I have:

"build-proj1":"tsc --build ./proj1/tsconfig.json"

It works, but for some reason, I noticed that it is extremely slow.

When I change it to:

"build-proj1":"tsc --project ./proj1/tsconfig.json"

It executes much faster and produces same result...

My tsconfig.json for reference:

{
    "compilerOptions": {
        "allowSyntheticDefaultImports": true,
        "module": "CommonJS",
        "target": "es2018",
        "lib": ["es2019"],
        "noImplicitAny": false,
        "declaration": false,
        "allowJs": true,
        "preserveConstEnums": true,
        "outDir": "./dist",
        "sourceMap": true,
        "skipLibCheck": true,
        "baseUrl": "./",
        "types": ["node"],
        "typeRoots": ["../node_modules/@types"],
        "strict": true,
        "esModuleInterop": true,
        "disableReferencedProjectLoad": true,
        "paths": {
            "root-common/*": ["../common/*"],
            "root-config/*": ["../config/*"],
            "root/*": ["../*"]
        }
    },
    "include": ["./**/*"],
    "exclude": ["node_modules", "**/*.spec.ts", "**/*.test.*", "./dist/**/*", "../common/**/*test.*"]
}

My question is what is the difference between --build and --project, and why --build would run much slower than --project?

Answer 1

According to tsc --help:

  --project, -p  Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.

  --build, -b  Build one or more projects and their dependencies, if out of date

The --project option compile a single project.

The --build option can be seen as a build orchestrator that find referenced projects, check if they are up-to-date, and build out-of-date projects in the correct order. See the documentation for details.

To answer your second question, the --build option is slower because it also compiles dependencies, but it should be faster at a second run, because it compiles only out-of-date projects.