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

After install, check it works:

tsc --version

You will see something like Version 6.0.3.

Option 2: Local Install (recommended for teams)

npm install --save-dev typescript

Then run it using npx:

npx tsc --version

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);

Now compile it:

tsc hello.ts

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

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

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!

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

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"]
}

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

---

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

Or use the short form:

tsc -w

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.

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

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

---

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

Or use the short form:

tsc -p tsconfig.prod.json

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

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

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

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

Output example:

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

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

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

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

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

Or use the flag directly:

tsc --incremental

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

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"
  }
}

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

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

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

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

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.

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

src/math.ts:

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

src/index.ts:

import { add } from "./math";

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

tsconfig.json:

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

package.json scripts:

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

Now run:

npm run build

You will get:

dist/
  index.js
  math.js

Run the output:

node dist/index.js
# 8

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