tsc -p (--project): compile with a specific tsconfig file or folder

tsc -p path compiles the TypeScript project described by a specific configuration file, or by the tsconfig.json inside a folder. Use it for alternative configs such as tsconfig.build.json, or to compile a project from another directory. Without -p, tsc looks for tsconfig.json in the current directory and then in parent directories. --project is the long form.

File or folder

npm init -y >/dev/null
npm install --silent --no-audit --no-fund typescript@7.0.2 >/dev/null 2>&1
mkdir -p app/src
echo 'export const answer: number = 42;' > app/src/index.ts
echo 'import { answer } from "./index.js"; if (answer !== 42) throw new Error("bad");' > app/src/index.test.ts
cat > app/tsconfig.json <<'EOF'
{ "compilerOptions": { "outDir": "dist", "rootDir": "src", "module": "nodenext", "target": "es2022", "strict": true, "types": [] }, "include": ["src"] }
EOF
cat > app/tsconfig.build.json <<'EOF'
{ "extends": "./tsconfig.json", "exclude": ["src/**/*.test.ts"] }
EOF
npx tsc -p app && find app/dist -name '*.js' | sort
rm -rf app/dist
npx tsc -p app/tsconfig.build.json && find app/dist -name '*.js' | sort

app/dist/index.js
app/dist/index.test.js
app/dist/index.js

-p app uses app/tsconfig.json; -p app/tsconfig.build.json uses the build config, which extends the base one and leaves the test file out. Paths inside a config (outDir, rootDir, include) are resolved relative to the file that contains them, not to the directory where you run tsc.

Errors you can get

npm init -y >/dev/null
npm install --silent --no-audit --no-fund typescript@7.0.2 >/dev/null 2>&1
mkdir -p src empty
echo 'export const a: number = 1;' > src/a.ts
echo '{ "compilerOptions": { "strict": true, "types": [] } }' > tsconfig.json
npx tsc -p missing.json; echo "exit: $?"
npx tsc -p empty; echo "exit: $?"
npx tsc src/a.ts; echo "exit: $?"
mkdir nots && echo '{ "include": ["lib"] }' > nots/tsconfig.json
npx tsc -p nots; echo "exit: $?"

error TS5058: The specified path does not exist: '/tmp/work/missing.json'.
exit: 1
error TS5081: Cannot find a tsconfig.json file at the current directory: /tmp/work/empty/tsconfig.json.
exit: 1
error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error.
exit: 1
error TS18003: No inputs were found in config file '/tmp/work/nots/tsconfig.json'. Specified 'include' paths were '["lib"]' and 'exclude' paths were '[]'.
exit: 2

TS5112 is a behaviour change worth knowing: before TypeScript 6, tsc src/a.ts silently ignored tsconfig.json and compiled with default options. Now it fails, and --ignoreConfig is the explicit way to get the old behaviour.

Typical uses

tsc -p tsconfig.build.json          # production build without tests
tsc -p tsconfig.build.json --noEmit # type check that config only
tsc -p packages/api                 # compile a sub-project from the repo root
tsc -p . --watch                    # same as plain tsc --watch in this folder
tsc -p tsconfig.json --showConfig   # print the resolved configuration

Options given on the command line override the config: tsc -p tsconfig.build.json --outDir out keeps everything else from the file. To see what the merged result is, including extends, use tsc --showConfig. For type checking without output, see tsc --noEmit.

Pitfalls

• An extended config resolves its own relative paths from its own folder. If a base config in configs/ sets "outDir": "dist", the output goes to configs/dist; put path options in the leaf config or use ${configDir} (TypeScript 5.5+), which expands to the folder of the config being compiled.
• rootDir defaults to the folder of the config being compiled in TypeScript 6 and 7, so a config in a subfolder that includes ../src needs an explicit rootDir; see tsc --outDir and --rootDir.

FAQ