TypeScript Installation & Running#

What it is#

TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. The official tsc compiler performs type-checking and emits JavaScript output. Several faster alternatives — ts-node, tsx, and Bun — allow running TypeScript files directly without a separate compile step, which is useful during development.

Install tsc#

TypeScript is installed as a dev dependency per-project. Avoid global installs so each project pins its own version.

npm install -D typescript

Verify the installation:

npx tsc --version

Output:

Version 5.4.5

Generate a starter tsconfig.json:

npx tsc --init

Output:

Created a new tsconfig.json with:
  target: es2016
  module: commonjs
  strict: true
  esModuleInterop: true
  skipLibCheck: true
  forceConsistentCasingInFileNames: true

Run TypeScript without a compile step#

ts-node#

ts-node is the classic Node.js TypeScript runner. It compiles files in-memory and executes them with Node.

npm install -D ts-node

npx ts-node src/index.ts

For ESM projects, use the --esm flag or the ts-node/esm loader:

npx ts-node --esm src/index.ts
# or
node --loader ts-node/esm src/index.ts

tsx#

tsx is a fast, ESM-compatible TypeScript runner built on esbuild. It starts faster than ts-node and handles .ts, .tsx, .mts, and .cts files transparently.

npm install -D tsx

npx tsx src/index.ts

Watch mode (re-runs on file changes):

npx tsx watch src/index.ts

Using as a Node.js loader (for programmatic use or legacy flags):

node --import tsx/esm src/index.ts

Bun#

Bun natively strips TypeScript types and executes the file directly — no separate package is needed.

bun run src/index.ts

Output:

Hello from TypeScript

[!TIP] For new projects, tsx is the recommended dev-time runner in 2026. It is faster than ts-node, supports both CJS and ESM, and requires no extra configuration.

Compile with tsc#

Basic compile#

Compiles all files listed in tsconfig.json and emits JavaScript to the configured outDir:

npx tsc

Watch mode#

Re-compiles whenever a source file changes:

npx tsc --watch

Output:

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

Type-check only (no emit)#

Validates types without writing any output files — useful in CI:

npx tsc --noEmit

Output (no errors):

(no output — exit code 0)

Output (with errors):

src/index.ts:5:10 - error TS2322: Type 'string' is not assignable to type 'number'.

5   const n: number = "hello";
              ~~~~~~~~~~~~~~~
Found 1 error.

Override output directory#

npx tsc --outDir dist

Compile a single file (bypasses tsconfig)#

npx tsc src/utils.ts --target ES2022 --module ESNext

[!WARNING] Passing individual file names to tsc disables tsconfig.json. All options must be specified via CLI flags when doing this.

Compile with source maps#

npx tsc --sourceMap

This emits a .js.map file alongside each .js file, enabling debuggers to map back to the original TypeScript source.

Project references#

Large monorepos split TypeScript code into multiple sub-projects. tsc --build (alias tsc -b) compiles them in dependency order and caches results.

npx tsc --build
npx tsc --build --watch       # watch all referenced projects
npx tsc --build --clean       # delete all build outputs
npx tsc --build --force       # rebuild even if up to date

A root tsconfig.json referencing sub-projects:

{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/api" },
    { "path": "./packages/ui" }
  ]
}

Each referenced package’s tsconfig.json must include "composite": true:

{
  "compilerOptions": {
    "composite": true,
    "outDir": "dist",
    "rootDir": "src"
  }
}

Useful tsc flags#

Choosing a runner#

[!NOTE] tsx and bun do not run the TypeScript type checker — they only strip types. Always run tsc --noEmit in CI to catch type errors.

TypeScript versions and release cadence#

TypeScript ships a minor version roughly every three months. Each minor (5.0, 5.1, 5.2, …) introduces new language features and may include breaking changes; patches are bug-fix only. The version installed in your project’s devDependencies is the version that governs every editor, every CI run, and every contributor’s compiler.

npm view typescript versions --json | tail -20

Output:

[
  "5.3.0",
  "5.3.2",
  "5.3.3",
  "5.4.0",
  "5.4.2",
  "5.4.3",
  "5.4.4",
  "5.4.5",
  "5.5.0",
  "5.5.2",
  "5.5.3",
  "5.6.0",
  "5.6.2",
  "5.7.2"
]

Pin to a specific minor in package.json to make builds deterministic. The ~ semver range lets the patch float (5.4.5 → 5.4.x) without accidentally moving to 5.5, where syntax may change:

{
  "devDependencies": {
    "typescript": "~5.4.5"
  }
}

Check the current install matches the lockfile:

npm ls typescript

Output:

my-project@1.0.0 /repo
└── typescript@5.4.5

Upgrade to the next minor in a controlled way — bump the package, run tsc --noEmit, then commit:

npm install -D typescript@5.5
npx tsc --noEmit

Output:

src/legacy.ts:12:5 - error TS2322: Type 'undefined' is not assignable to type 'string'.

12     const v: string = maybeUndefined();
       ~~~~~~~~~~~~~~~~

Found 1 error.

Every new minor often surfaces additional errors as the type-checker gets stricter. Read the release notes for breaking-change call-outs before upgrading.

Global vs local tsc#

tsc installed globally (npm install -g typescript) puts a single binary on $PATH that ignores your project’s version. The risk: contributor A’s global is 5.0 and emits one shape of output; contributor B’s global is 5.7 and emits another. Lock everything to the local install via npx tsc (or pnpm tsc, bun tsc, yarn tsc), which resolves from node_modules/.bin first.

which tsc
npx tsc --version

Output:

/Users/alice/.nvm/versions/node/v22.10.0/bin/tsc
Version 5.4.5

Notice which tsc finds a global binary first, but npx tsc runs the project’s node_modules/.bin/tsc. Always invoke via npx/pnpm exec/bun x so the lockfile rules.

For a project where npx is annoying, add an npm script that aliases tsc to the local binary:

{
  "scripts": {
    "tsc": "tsc",
    "typecheck": "tsc --noEmit",
    "build": "tsc"
  }
}

npm run typecheck

Output:

> tsc --noEmit
(no output — exit code 0)

The shell script form (npm run …) prepends node_modules/.bin to $PATH automatically — every binary listed in any installed package becomes callable from a script without npx.

Choosing a TypeScript distribution#

Most projects use the official typescript package from npm, but several alternatives ship faster compilers or different feature sets. They are not drop-in replacements — each has trade-offs.

The recommendation in 2026: use the official typescript package for type-checking and .d.ts emit, and use a bundler (Vite, esbuild, Bun) for the actual JS output. Do not try to make swc or esbuild replace tsc — they do not type-check.

npm install -D typescript @swc/core

Output: (none — exits 0 on success)

devDependencies layout for a TypeScript project#

A modern TypeScript project’s package.json typically lists these dev dependencies. Each entry is here for a reason; deleting one silently breaks a workflow.

{
  "name": "my-app",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/index.ts",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "lint": "eslint src"
  },
  "devDependencies": {
    "typescript": "~5.4.5",
    "tsx": "^4.19.0",
    "@types/node": "^22.5.0",
    "vitest": "^2.0.0",
    "eslint": "^9.0.0",
    "@typescript-eslint/parser": "^8.0.0",
    "@typescript-eslint/eslint-plugin": "^8.0.0"
  }
}

The standard four:

• typescript — the compiler itself.
• tsx — fast dev-time runner (replaces ts-node).
• @types/node — type declarations for Node’s stdlib (fs, path, process, etc.). Required for any Node script.
• @typescript-eslint/* — TypeScript-aware ESLint rules.

npm install -D typescript tsx @types/node

Output:

added 3 packages in 1.2s

@types/* packages#

Most npm packages either ship their own .d.ts files (bundled types) or have a community-maintained @types/<name> package on the @types scope. The TypeScript compiler auto-discovers any @types/* package in node_modules — you don’t need to register them anywhere.

npm install -D @types/node @types/express @types/lodash

Output:

added 3 packages in 0.8s

For a library that doesn’t have @types/<name> and doesn’t bundle types, TypeScript errors with TS7016. The fix is either to author a one-line ambient declaration (see .d.ts files) or to install the community types if they exist:

npm install -D @types/some-library

Output: (none — exits 0 on success)

A handful of types packages are pinned to specific runtime versions — @types/node@22.x for Node 22, @types/node@20.x for Node 20. Match the runtime you’re targeting, not the latest:

node --version
npm install -D @types/node@22

Output:

v22.10.0
added 1 package in 0.4s

Editor integration#

Every IDE that supports TypeScript reads from the same tsserver binary inside node_modules/typescript/lib/tsserver.js. The editor and tsc see the same world if (and only if) they use the same version.

VS Code workspace TypeScript version#

VS Code ships its own bundled TypeScript and uses it by default. For a per-project version, click the version indicator in the status bar (bottom-right when a .ts file is open) and pick “Use Workspace Version”. The selection is saved to .vscode/settings.json:

{
  "typescript.tsdk": "node_modules/typescript/lib"
}

This ensures every developer who opens the project sees the same compiler. Commit this setting.

Neovim / LSP#

typescript-language-server (or vtsls, a newer fork) wraps tsserver and exposes it over LSP. Pick the project’s TypeScript by setting the server’s tsdk option:

require('lspconfig').vtsls.setup({
  settings = {
    typescript = {
      tsdk = vim.fn.getcwd() .. '/node_modules/typescript/lib',
    },
  },
})

Refresh the editor after upgrading#

After npm install -D typescript@<new-version>, the running editor still has the old tsserver in memory. VS Code: Command Palette → TypeScript: Restart TS Server. Neovim: :LspRestart.

# To force every editor's restart on macOS, touch the project's tsconfig:
touch tsconfig.json

Output: (none — exits 0 on success)

Cross-runtime: TypeScript outside Node.js#

Node is the most common host for TypeScript, but several other runtimes treat TypeScript as a first-class input. Each handles the type-strip / type-check split differently — none of these replaces tsc for type-checking. See ts-node, tsx & friends for the deep comparison.

Use the right tool for the job, but always run tsc --noEmit somewhere in the chain. Stripping is not checking.

node --experimental-strip-types src/index.ts
bun src/index.ts
deno run --allow-net src/index.ts

Output:

Hello from TypeScript

What tsc actually does, end-to-end#

Knowing what happens between npx tsc and the bytes hitting your dist/ directory makes diagnosing build problems much easier. The compiler runs five passes:

1. Locate inputs — read tsconfig.json, expand include/exclude/files, plus every transitive import.
2. Parse — produce AST nodes for every .ts / .tsx / .d.ts file.
3. Bind — assign each declaration a symbol and link references back to declarations.
4. Check — run the type-checker pass-by-pass, surfacing errors.
5. Emit — write .js, .d.ts, and .map files according to compilerOptions.

You can interrupt the pipeline at each stage with a flag. --noEmit stops after pass 4. --declaration --emitDeclarationOnly writes only .d.ts and skips .js. --listFiles prints every file scanned during pass 1.

npx tsc --listFiles --noEmit | head -10

Output:

/repo/node_modules/typescript/lib/lib.es5.d.ts
/repo/node_modules/typescript/lib/lib.es2015.d.ts
/repo/node_modules/typescript/lib/lib.es2016.d.ts
/repo/node_modules/typescript/lib/lib.dom.d.ts
/repo/node_modules/@types/node/index.d.ts
/repo/src/index.ts
/repo/src/util.ts

--diagnostics prints timing breakdown for each pass:

npx tsc --diagnostics --noEmit

Output:

Files:                          47
Lines:                       18421
Identifiers:                 36842
Symbols:                     12387
Types:                        4192
Parse time:                   0.42s
Bind time:                    0.12s
Check time:                   1.87s
Emit time:                    0.00s
Total time:                   2.41s

When a build feels slow, this is where to look. Long bind time points to too many imports; long check time points to gnarly generic types. The compiler API exposes the same numbers programmatically via ts.performance.

Comparison with Python and other ecosystems#

TypeScript installation differs from typed languages in adjacent ecosystems. The mental model “TypeScript = Python’s mypy” is useful but incomplete.

The most surprising-for-newcomers part of TypeScript: there is no runtime — the type system disappears. Compare with Rust where the compiler enforces types end-to-end, or Python where mypy is purely advisory but the runtime exists.

Common pitfalls#

1. Calling a global tsc by mistake — which tsc resolves to the global, but the project’s version is in node_modules. Always use npx tsc or an npm script.
2. @types/node version doesn’t match runtime — process.env.X typed as string | undefined even after augmenting ProcessEnv if @types/node is from a different major. Pin it to the Node major you run.
3. Mixing dev runners — using ts-node in dev, tsc in build, and an editor that picks a different bundled TypeScript. The three should agree on tsconfig.json; pick one TypeScript version everywhere.
4. npm install -g typescript only — works, until a contributor’s global is a different minor. Always install locally and reference via npx.
5. VS Code says “Use Workspace Version” but you ignore the prompt — VS Code’s bundled TypeScript is older than the project’s, so the editor flags errors the build doesn’t. Always commit .vscode/settings.json with typescript.tsdk.
6. tsx not installed in CI — your dev runs fine because tsx is in node_modules, but CI uses npm ci --omit=dev and skips it. Move tsx from devDependencies to wherever the CI script needs it, or run the build before --omit=dev.
7. bun run reading the wrong package script — Bun runs package.json scripts but ignores pre*/post* hooks. If your prebuild step is critical, call it explicitly.
8. Mixing tsx and node shebangs — the file’s first line decides who runs it. #!/usr/bin/env -S npx tsx works for the author but fails for users without tsx installed. Build to JS for distribution.
9. emitDeclarationOnly without declaration: true — tsc silently emits nothing. Always pair them.
10. Stale .tsbuildinfo after an upgrade — tsc may skip recompilation believing nothing changed. Run tsc -b --force once after upgrading the compiler.

Real-world recipes#

Pin TypeScript across a monorepo#

Every workspace inherits the root typescript install via npm/pnpm/Bun hoisting. Pin in one place; never re-install at a child workspace.

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"],
  "devDependencies": {
    "typescript": "~5.4.5",
    "tsx": "^4.19.0"
  }
}

pnpm install
pnpm -r exec tsc --version

Output:

packages/shared  | Version 5.4.5
packages/ui      | Version 5.4.5
packages/app     | Version 5.4.5

Migrate from ts-node to tsx#

The standard 2026 dev runner migration — same package.json shape, two-line diff.

npm uninstall ts-node
npm install -D tsx

Output:

removed 14 packages in 0.5s
added 1 package in 0.3s

Update package.json:

{
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "start": "node dist/server.js"
  }
}

npm run dev

Output:

[tsx] watching src/server.ts
Server ready on http://localhost:3000

If you used ts-node’s register hook for tests (mocha -r ts-node/register), swap to tsx (mocha --import tsx).

Type-check in CI without emitting#

The single most common CI script: type-check the project, fail the build on errors, write nothing to disk.

npx tsc --noEmit

Output:

(no output — exit code 0)

For monorepos with project references, use tsc -b --noEmit instead — it walks the reference graph and skips up-to-date sub-projects.

npx tsc -b --noEmit

Output:

(no output — exit code 0)

Install TypeScript without Node (Bun-first project)#

If your project never touches Node — say, a Cloudflare Worker built with Bun — TypeScript still installs via Bun’s package manager. Bun reads package.json and writes a bun.lock:

bun add -d typescript @types/bun

Output:

bun add v1.2.18

 installed typescript@5.4.5
 installed @types/bun@1.1.5

 2 packages installed [123.00ms]

The @types/bun package provides TypeScript declarations for the Bun.* namespace, bun:test, and Bun’s bundler API. With it in devDependencies, your editor sees Bun.serve(), Bun.file(), and import { describe } from "bun:test" without errors.

Add TypeScript to an existing JavaScript project#

Three commands turn a plain JS repository into a TypeScript-aware one — no rewrite required. allowJs: true lets tsc type-check existing .js files; you migrate file-by-file.

npm install -D typescript @types/node
npx tsc --init

Output:

Created a new tsconfig.json with:
  target: es2016
  module: commonjs
  strict: true
  esModuleInterop: true
  skipLibCheck: true
  forceConsistentCasingInFileNames: true

Edit tsconfig.json to enable JavaScript checking:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

npx tsc --noEmit

Output:

(no output — exit code 0)

Now rename one file at a time from .js to .ts and watch the type errors appear. See project references for surgical per-directory migration.

Reproduce the project compiler version exactly#

When tracking down “works on my machine” type errors, compare the TypeScript version in use across machines.

npx tsc --version
npm ls typescript --json | jq -r '.dependencies.typescript.version'

Output:

Version 5.4.5
5.4.5

If those two disagree, an editor or a script is using a different version. Force the local version via npx, restart the editor, and confirm again.