How to Use the TypeScript Compiler (tsc) to Compile Your Code

TLDR

tsc is the TypeScript compiler. It turns your .ts files into .js files that Node.js and browsers can run. Install it with npm install -g typescript. Run tsc to compile your whole project. Run tsc --watch to auto-compile on every file save. Run tsc --noEmit to check for errors without creating any files.

What is the TypeScript Compiler?

The TypeScript compiler is a tool called tsc. It reads your TypeScript files and turns them into JavaScript files.

Your browser and Node.js cannot run TypeScript directly. They only understand JavaScript. So tsc acts as the bridge between what you write and what actually runs.

Think of tsc like a spell checker for your code. It finds problems before your code ever runs. Then it produces clean JavaScript output for you.

How to Install the TypeScript Compiler

You install tsc using npm. There are two ways to do this.

Option 1: Global Install (runs anywhere on your computer)

npm install -g typescript

Enter fullscreen mode Exit fullscreen mode

After install, check it works:

tsc --version

Enter fullscreen mode Exit fullscreen mode

You will see something like Version 6.0.3.

Option 2: Local Install (recommended for teams)

npm install --save-dev typescript

Enter fullscreen mode Exit fullscreen mode

Then run it using npx:

npx tsc --version

Enter fullscreen mode Exit fullscreen mode

Which one should you use? Use a local install for project work. This makes sure everyone on your team uses the same TypeScript version. Use a global install only for quick personal experiments.

How to Compile a Single TypeScript File

The simplest way to use tsc is to pass it a single file.

Create a file called hello.ts:

const message: string = "Hello, TypeScript!";
console.log(message);

Enter fullscreen mode Exit fullscreen mode

Now compile it:

tsc hello.ts

Enter fullscreen mode Exit fullscreen mode

This creates a new file called hello.js in the same folder:

var message = "Hello, TypeScript!";
console.log(message);

Enter fullscreen mode Exit fullscreen mode

Notice that TypeScript removed the : string type annotation. The output is plain JavaScript that Node.js can run.

Run the output file:

node hello.js
# Hello, TypeScript!

Enter fullscreen mode Exit fullscreen mode

Important: When you pass a file directly to tsc, it ignores your tsconfig.json. It uses its own default settings instead. For real projects, always use tsconfig.json.

How to Compile Your Whole Project

For most projects, you will not compile one file at a time. You will compile the whole project using tsconfig.json.

Just run tsc with no arguments:

tsc

Enter fullscreen mode Exit fullscreen mode

TypeScript will look for a tsconfig.json in your current folder. It reads the settings and compiles all included .ts files.

If your tsconfig.json has this setup:

{
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"]
}

Enter fullscreen mode Exit fullscreen mode

Running tsc will take all files from src/ and put compiled .js files into dist/.

Before tsc:             After tsc:
src/                    src/
  index.ts                index.ts
  utils.ts                utils.ts
                        dist/
                          index.js
                          utils.js

Enter fullscreen mode Exit fullscreen mode

How to Use Watch Mode (Auto-Compile on Save)

Running tsc by hand every time you change a file is slow. Watch mode fixes this.

tsc --watch

Enter fullscreen mode Exit fullscreen mode

Or use the short form:

tsc -w

Enter fullscreen mode Exit fullscreen mode

Now TypeScript watches all your files. Every time you save a .ts file, it recompiles automatically. You will see output like this:

[12:10:01 PM] Starting compilation in watch mode...
[12:10:02 PM] Found 0 errors. Watching for file changes.

[12:10:45 PM] File change detected. Starting incremental compilation...
[12:10:45 PM] Found 0 errors. Watching for file changes.

Enter fullscreen mode Exit fullscreen mode

To stop watch mode, press CTRL + C in your terminal.

Tip: Keep watch mode running in a terminal tab while you code. You will see errors right away instead of finding them later.

How to Type-Check Without Creating Files

Sometimes you just want to check for type errors. You do not want to produce any JavaScript output.

Use the --noEmit flag:

tsc --noEmit

Enter fullscreen mode Exit fullscreen mode

This runs all the type checks and prints any errors. But it does not create any .js files.

This is very useful in two places:

• In your CI/CD pipeline to make sure code passes type checks before deploying
• Before a commit to catch bugs without building the whole project

# Check types only, no output files
tsc --noEmit

# Check types in watch mode (good during development)
tsc --noEmit --watch

Enter fullscreen mode Exit fullscreen mode

How to Use a Specific Config File

By default, tsc looks for tsconfig.json in your current folder. You can tell it to use a different config file with --project.

tsc --project tsconfig.prod.json

Enter fullscreen mode Exit fullscreen mode

Or use the short form:

tsc -p tsconfig.prod.json

Enter fullscreen mode Exit fullscreen mode

This is useful when you have different builds. For example:

Config File Used For tsconfig.json Default development settings tsconfig.prod.json Production build with stricter settings tsconfig.test.json Test environment settings

Most Useful tsc CLI Flags

Here is a list of the flags you will use the most.

Flag Short Form What It Does --watch -w Recompile automatically on file changes --noEmit Check types only, no JS output --project -p Use a specific config file --init Create a new tsconfig.json --version -v Show the TypeScript version --help -h Show all available options --listFiles Print all files being compiled --showConfig Print the full merged config --incremental Speed up builds by caching --strict Enable strict mode for this run --target Set the JS output version for this run --outDir Set the output folder for this run

How to Pass Flags Without tsconfig.json

You can pass compilerOptions directly from the command line. This is useful for quick tests.

# Compile a file targeting ES2022 output
tsc index.ts --target ES2022

# Compile two files into one output file
tsc app.ts utils.ts --target ESNext --outFile bundle.js

# Compile with strict mode on
tsc index.ts --strict

Enter fullscreen mode Exit fullscreen mode

Remember: Flags passed on the command line override what is in your tsconfig.json. Use this only for testing and one-off tasks.

How to Debug Compilation Problems

When something goes wrong with compilation, these two flags help you figure out what is happening.

--listFiles

This shows you every file TypeScript is including in the compilation.

tsc --listFiles

Enter fullscreen mode Exit fullscreen mode

Output example:

/usr/local/lib/node_modules/typescript/lib/lib.es2022.d.ts
/home/user/project/src/index.ts
/home/user/project/src/utils.ts

Enter fullscreen mode Exit fullscreen mode

Use this when TypeScript is compiling files you did not expect.

--showConfig

This prints the full merged config that TypeScript is actually using.

tsc --showConfig

Enter fullscreen mode Exit fullscreen mode

Output example:

{
  "compilerOptions": {
    "target": "es2022",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "files": [
    "./src/index.ts",
    "./src/utils.ts"
  ]
}

Enter fullscreen mode Exit fullscreen mode

Use this when you are not sure what settings are active. This is especially helpful when you use extends to inherit from another config file.

Understanding tsc Exit Codes

Exit codes tell you if the compilation succeeded or failed. This matters a lot in CI/CD pipelines.

Exit Code Meaning 0 Compilation succeeded with no errors 1 Compilation failed with errors 2 Invalid compiler arguments were passed

You can check the exit code in your shell like this:

tsc --noEmit
echo $?   # Prints 0 if no errors, 1 if there are errors

Enter fullscreen mode Exit fullscreen mode

In a GitHub Actions workflow, you can use this pattern:

- name: Type check
  run: npx tsc --noEmit

Enter fullscreen mode Exit fullscreen mode

If there are type errors, the pipeline stops and fails. This prevents broken code from being deployed.

How to Speed Up Compilation with Incremental Mode

For large projects, tsc can take a long time to compile. Incremental mode speeds things up by remembering what it compiled last time.

Turn it on in your tsconfig.json:

{
  "compilerOptions": {
    "incremental": true
  }
}

Enter fullscreen mode Exit fullscreen mode

Or use the flag directly:

tsc --incremental

Enter fullscreen mode Exit fullscreen mode

The first run will take the same amount of time. But every run after that will be much faster because TypeScript only recompiles files that changed.

TypeScript stores a cache in a file called .tsbuildinfo. Do not delete this file if you want faster builds.

my-project/
├── src/
├── dist/
├── tsconfig.json
└── tsconfig.tsbuildinfo    <-- build cache, keep this

Enter fullscreen mode Exit fullscreen mode

Tip: Add .tsbuildinfo to your .gitignore file. There is no need to commit it.

How to Use tsc in Your package.json Scripts

Most developers add tsc commands to their package.json so the team does not have to remember flags.

{
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch",
    "type-check": "tsc --noEmit",
    "type-check:watch": "tsc --noEmit --watch"
  }
}

Enter fullscreen mode Exit fullscreen mode

Now your team can run simple commands:

npm run build           # Compile the project
npm run build:watch     # Compile and watch for changes
npm run type-check      # Check types without building

Enter fullscreen mode Exit fullscreen mode

This is a clean workflow that works for every developer on your team.

Common tsc Errors and What They Mean

Here are some errors you will see when starting out.

Error: Cannot find a tsconfig.json file

error TS5083: Cannot read file '/project/tsconfig.json'.

Enter fullscreen mode Exit fullscreen mode

Fix: Make sure you are in the right folder. Run tsc --init if you do not have a tsconfig.json yet.

Error: Argument of type is not assignable

error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

Enter fullscreen mode Exit fullscreen mode

Fix: You passed the wrong type to a function. Check your function’s expected parameter types.

Error: rootDir is expected to contain all source files

error TS6059: File '/project/tests/app.test.ts' is not under 'rootDir' '/project/src'.

Enter fullscreen mode Exit fullscreen mode

Fix: Your rootDir does not include all your .ts files. Update rootDir or adjust your include list.

Error: Cannot write file because it would overwrite input file

error TS5055: Cannot write file 'index.js' because it would overwrite input file.

Enter fullscreen mode Exit fullscreen mode

Fix: Set an outDir in your tsconfig.json. TypeScript cannot save output files to the same place as source files.

Full Workflow Example

Here is a complete example of a TypeScript project using tsc the right way.

Project structure:

my-app/
├── src/
│   ├── index.ts
│   └── math.ts
├── tsconfig.json
└── package.json

Enter fullscreen mode Exit fullscreen mode

src/math.ts:

export function add(a: number, b: number): number {
  return a + b;
}

Enter fullscreen mode Exit fullscreen mode

src/index.ts:

import { add } from "./math";

const result: number = add(5, 3);
console.log(result);

Enter fullscreen mode Exit fullscreen mode

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "strict": true,
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src"]
}

Enter fullscreen mode Exit fullscreen mode

package.json scripts:

{
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "type-check": "tsc --noEmit"
  }
}

Enter fullscreen mode Exit fullscreen mode

Now run:

npm run build

Enter fullscreen mode Exit fullscreen mode

You will get:

dist/
  index.js
  math.js

Enter fullscreen mode Exit fullscreen mode

Run the output:

node dist/index.js
# 8

Enter fullscreen mode Exit fullscreen mode

That is a clean, working TypeScript workflow using tsc.

FAQ

Q: Do I need to run tsc every time I save a file?
No. Use tsc --watch and it will recompile automatically every time you save.

Q: Can I run TypeScript files without compiling?
Yes. Tools like ts-node and tsx can run TypeScript directly without a separate compile step. But for production use, you should always compile with tsc first.

Q: What is the difference between tsc and npx tsc?
If you installed TypeScript globally, use tsc. If you installed it locally in your project, use npx tsc. npx picks up the local version from your node_modules.

Q: Does tsc minify my JavaScript output?
No. tsc does not minify code. It only compiles TypeScript to JavaScript. For minification, use a bundler like Vite, Webpack, or esbuild.

Q: Why does tsc still output files even when there are errors?
By default, tsc emits JavaScript even if there are type errors. To stop this, set "noEmitOnError": true in your tsconfig.json.

Q: How do I compile only changed files to make builds faster?
Use "incremental": true in your tsconfig.json. TypeScript will cache the last build and only recompile changed files.

What You Learned

• tsc is the TypeScript compiler that turns .ts files into .js files
• Install with npm install --save-dev typescript and run with npx tsc
• Run tsc to compile your whole project using tsconfig.json
• Use --watch to auto-compile on every file save
• Use --noEmit to type-check without creating files
• Use --project to point to a specific config file
• Use --showConfig and --listFiles to debug compilation issues
• Add tsc commands to your package.json scripts so your whole team can use them

Sources: TypeScript Official tsc CLI Docs | TypeScript TSConfig Reference