Setting Up TypeScript

Installing TypeScript

TypeScript should be installed as a project dev dependency rather than globally. This keeps the version pinned to your project and ensures everyone on the team uses the same compiler version — avoiding subtle differences between machines.

npm install -D typescript

This gives you the tsc compiler. Confirm it works:

npx tsc --version
# Version 5.x.x

For global use (optional, not recommended for teams):

npm install -g typescript
tsc --version

Your First Compile

Before adding a tsconfig.json, you can compile a single file directly. This is useful for getting a feel for what the compiler produces.

Create a file hello.ts:

// Type annotations are stripped during compilation
const greeting: string = "Hello, TypeScript!";
console.log(greeting);

Compile it:

npx tsc hello.ts

This produces hello.js in the same directory with the type annotations removed. Run it:

node hello.js
# Hello, TypeScript!

tsconfig.json

For any real project you need a tsconfig.json. It tells the compiler where your source files live, what JavaScript to emit, and which strictness checks to apply. Without it, you are relying on defaults that may not match your environment or safety requirements.

Generate a starter config:

npx tsc --init

Here is a well-commented config for a modern Node.js project:

{
  "compilerOptions": {
    // What version of JS to emit — ES2022 is safe for Node 16+
    "target": "ES2022",

    // Module system for emitted code
    "module": "CommonJS",

    // Where to put compiled JS files
    "outDir": "./dist",

    // Where TypeScript looks for source files
    "rootDir": "./src",

    // Enable all strict type-checking flags — always turn this on
    "strict": true,

    // Allow default imports from modules with no default export
    "esModuleInterop": true,

    // Skip type checking of declaration files in node_modules (faster builds)
    "skipLibCheck": true,

    // Generate .d.ts declaration files alongside JS output (useful for libraries)
    "declaration": true,

    // Generate source maps for debugging in the original .ts files
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

For a browser/bundler project (Vite, webpack), swap module for ESNext and remove outDir since the bundler handles output.

Key tsconfig Options Explained

These three options have the biggest impact on your development experience and safety. Understanding them saves a lot of confusion early on.

strict: true enables a bundle of checks that catch real bugs:

• strictNullChecks — null and undefined are not assignable to other types, forcing you to handle them explicitly
• noImplicitAny — variables must have an explicit type if it can’t be inferred, preventing accidental any creep
• strictFunctionTypes — stricter checking of function parameter types

Always enable strict: true. The bugs it catches are real and common.

target controls which JavaScript syntax features are emitted. ES2022 is a safe modern choice for Node 16+. Use ES5 only if you must support very old browsers without a separate transpiler.

module controls how import/export is compiled. Use CommonJS for Node.js without ESM, ESNext or NodeNext for modern Node with "type": "module" in package.json.

ts-node for Development

Running tsc and then node on every change during development is tedious. ts-node solves this by compiling TypeScript on the fly, letting you run .ts files directly. This shortens the feedback loop significantly.

npm install -D ts-node
npx ts-node src/index.ts

For watch mode during development — auto-restarts on file changes:

npm install -D ts-node-dev
npx ts-node-dev --respawn src/index.ts

Add scripts to package.json to make these easy to run:

{
  "scripts": {
    "dev": "ts-node-dev --respawn src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Project Structure

Keeping source and compiled output in separate directories prevents confusion and makes it easy to gitignore the build artifacts. This is the standard layout most TypeScript projects follow:

my-project/
├── src/
│   ├── index.ts
│   ├── utils/
│   │   └── helpers.ts
│   └── types/
│       └── index.ts
├── dist/           # compiled output — add this to .gitignore
├── tsconfig.json
├── package.json
└── .gitignore

Add dist/ to .gitignore — compiled output is derived from source and should never be committed.

VS Code Setup

VS Code has TypeScript support built in via its own bundled TypeScript language server. To use your project’s TypeScript version instead (important when your project uses a newer version than VS Code bundles):

1. Open the command palette (Ctrl+Shift+P)
2. Run TypeScript: Select TypeScript Version
3. Choose Use Workspace Version

Recommended extensions that improve the TypeScript experience significantly:

• Error Lens — shows type errors inline in the editor, right next to the code
• Pretty TypeScript Errors — formats complex nested type errors into readable output

Useful VS Code settings for TypeScript (settings.json):

{
  "typescript.preferences.quoteStyle": "double",
  "typescript.updateImportsOnFileMove.enabled": "always",
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

Extending a Base Config

Microsoft publishes shareable base configs for common environments so you don’t have to maintain every compiler option yourself. This is the recommended approach for new projects — it inherits community best practices and stays up to date.

npm install -D @tsconfig/node22

{
  "extends": "@tsconfig/node22/tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

This keeps your tsconfig.json minimal while inheriting best practices for your target platform.

Running the Build

These are the three compiler commands you will use day to day:

# Type-check without emitting files — fast, great for CI
npx tsc --noEmit

# Full build — compile everything to dist/
npx tsc

# Watch mode — recompiles on every file save during development
npx tsc --watch

--noEmit is particularly useful in CI pipelines to verify your types without producing output that would then need to be discarded.