tsc file.ts: compile a single file (and why tsconfig.json is ignored)

npx tsc file.ts compiles just that file (and the files it imports) to file.js with the default compiler options: any tsconfig.json in the folder is not used. Since TypeScript 6.0 tsc refuses the mix and stops with error TS5112; add --ignoreConfig to compile the single file anyway, or drop the file name and run npx tsc to build the project with its config.

The TS5112 error and both fixes

npm init -y >/dev/null
npm install --silent --no-audit --no-fund --save-dev typescript@7.0.2 >/dev/null 2>&1
npx tsc --init >/dev/null
echo 'const greet = (name: string): string => `hello ${name}`; console.log(greet("ts"));' > hello.ts
npx tsc hello.ts
echo "--- with --ignoreConfig"
npx tsc --ignoreConfig hello.ts && node hello.js
echo "--- a type error"
echo 'const n: number = "x";' > bad.ts
npx tsc --ignoreConfig bad.ts

error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error.
--- with --ignoreConfig
hello ts
--- a type error
bad.ts(1,7): error TS2322: Type 'string' is not assignable to type 'number'.

With --ignoreConfig the file compiles with tsc's built-in defaults, and node hello.js runs the result. A type error is still reported, and the .js file is written anyway unless you add --noEmitOnError: that is what exit status 2 means (errors found, output generated), while TS5112 exits with 1.

Ways to compile

Pitfalls

• Settings that seem to be ignored. On TypeScript 5.x and older, tsc file.ts silently drops strict, target, outDir, paths and everything else in tsconfig.json. If a single-file build behaves differently from the project build, that is the reason.
• Default options are old-fashioned. Without a config, strict is off and the target and module defaults differ from the tsc --init template, so code that passes this way can fail in the real build. Check with npx tsc --noEmit on the project.
• Output next to the source. Without --outDir, hello.js lands beside hello.ts.
• Imports are followed. Compiling one file also compiles every local file it imports, so "single file" can still emit several .js files.

Confirm it worked

After npx tsc --ignoreConfig file.ts, a file.js appears and echo $? is 0 when there were no errors. For a project build, npx tsc --showConfig shows which config and options tsc used.

FAQ