Getting Started & the Compiler

TypeScript is JavaScript plus a static type layer. You write ordinary JavaScript and add type annotations, interfaces and type aliases on top. Nearly every valid JavaScript file is also syntactically valid TypeScript — the compiler may complain about types in it, but it understands it. The type layer exists only for tools: the compiler, your editor, your linter.

The compiler (tsc) does two independent jobs. It checks: reads your code, works out the type of every expression, and reports anything that doesn't fit. And it emits: strips the type syntax out and writes plain JavaScript, optionally rewriting newer syntax for older runtimes. These two jobs barely talk to each other. By default tsc writes the JavaScript even when the check found errors, and tools like esbuild, Vite, tsx and Node itself do only the second job.

A good mental model is scaffolding around a building. The types help you build the thing correctly, but they are taken down before the building opens. At runtime there is no interface, no type, no annotation — just the JavaScript that was underneath. That one fact explains most of TypeScript's "surprises": you can't check a type at runtime, a wrong JSON.parse result isn't caught, and two types with the same shape are interchangeable.

export interface User {
  id: number;
  name: string;
}

export type Role = "admin" | "viewer";

export function greet(user: User, role: Role): string {
  return `Hello ${user.name} (${role})`;
}

const rohit: User = { id: 1, name: "Rohit" };
console.log(greet(rohit, "admin")); // Hello Rohit (admin)

// What tsc emits (user.js)
export function greet(user, role) {
    return `Hello ${user.name} (${role})`;
}
const rohit = { id: 1, name: "Rohit" };
console.log(greet(rohit, "admin"));

interface User {
  id: number;
  name: string;
}

const user: User = JSON.parse('{"id":"42"}'); // compiles: JSON.parse returns any
console.log(user.id, typeof user.id); // 42 string — the type said number
console.log(user.name.toUpperCase()); // compiles, then TypeError at runtime

function isUser(value: unknown) {
  return value instanceof User; // ❌ 'User' only refers to a type, but is being used as a value here.
}

interface Point {
  x: number;
  y: number;
}

class Vector {
  x: number;
  y: number;
  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }
}

function distanceFromOrigin(p: Point): number {
  return Math.hypot(p.x, p.y);
}

distanceFromOrigin(new Vector(3, 4)); // 5 — Vector never mentions Point

const reading = { x: 6, y: 8, label: "sensor" };
distanceFromOrigin(reading); // 10 — extra properties are fine

distanceFromOrigin({ x: 1, y: 1, label: "inline" }); // ❌ Object literal may only specify known properties, and 'label' does not exist in type 'Point'.

Engines run JavaScript, so something has to turn .ts into .js before (or as) the code runs. There are three ways to do it, and the important difference between them is whether type-checking happens on the way.

1. Compile ahead of time with tsc. Check and emit to an output folder, then run the JavaScript. This is the classic production setup for Node services and libraries.
2. Run through a loader: ts-node or tsx. The tool hooks into Node's module loading and transpiles each .ts file in memory as it's imported. No dist folder. ts-node uses the TypeScript compiler and type-checks by default; tsx uses esbuild and only strips types.
3. Let Node strip the types itself. Node 22.6 added --experimental-strip-types, and since Node 23.6 (and 22.18) it's on by default: node app.ts just works for code that uses only erasable syntax.

The mental model: running and checking are separate jobs. Options 2 (with tsx) and 3 make running fast precisely because they skip checking. You then run tsc --noEmit separately — in your editor, a pre-commit hook or CI — to get the type errors.

# 1. Compile, then run the JavaScript
npx tsc                      # check + emit to outDir (e.g. dist/)
node dist/main.js

# Just check, emit nothing — the usual CI step with any of the options below
npx tsc --noEmit

# 2a. ts-node: compile in memory with the TypeScript API (type-checks unless --transpileOnly)
npx ts-node src/main.ts

# 2b. tsx: strip types with esbuild, no type-checking, fast; has a watch mode
npx tsx src/main.ts
npx tsx watch src/main.ts

# 3. Node's built-in type stripping (Node 23.6+ / 22.18+, no flag)
node src/main.ts

const port: number = "8080"; // ❌ Type 'string' is not assignable to type 'number'.
console.log(port + 1);

enum Level {
  Info,
  Warn,
}

class Logger {
  constructor(private prefix: string) {}

  log(level: Level, msg: string) {
    console.log(`${this.prefix} [${Level[level]}] ${msg}`);
  }
}

new Logger("app").log(Level.Warn, "disk almost full");

$ node logger.ts
SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode

const Level = { Info: 0, Warn: 1 } as const;
type Level = (typeof Level)[keyof typeof Level]; // 0 | 1

const levelNames = ["Info", "Warn"] as const;

class Logger {
  private prefix: string; // `private` is just erased — fine

  constructor(prefix: string) {
    this.prefix = prefix;
  }

  log(level: Level, msg: string) {
    console.log(`${this.prefix} [${levelNames[level]}] ${msg}`);
  }
}

new Logger("app").log(Level.Warn, "disk almost full"); // app [Warn] disk almost full

tsconfig.json marks the root of a TypeScript project and tells tsc (and your editor) how to treat it. There are dozens of options, but they answer only four questions:

1. Which files? include, exclude, files.
2. What environment does the code run in? target, lib, types — which syntax and which globals (window, process) exist.
3. What should come out, and in what module format? module, outDir, rootDir, sourceMap, declaration — or noEmit if another tool produces the JavaScript.
4. How strict should checking be? strict plus a few extra flags.

The defaults moved a lot recently: TypeScript 6.0 changed most of them and deprecated old options, and TypeScript 7 removed those options. In TypeScript 7, strict is on by default, target defaults to es2025 (and es5 is gone), types defaults to [] (no @types packages are loaded unless you list them), rootDir defaults to the folder containing tsconfig.json, and baseUrl and the old node/classic module resolution are gone. Being explicit about the important options protects you from these shifts. npx tsc --init writes a sensible starter, and npx tsc --showConfig prints the final config after extends and defaults are applied.

A Node service or library compiled with tsc

{
  "compilerOptions": {
    // Output: what JavaScript comes out, and where
    "target": "es2024",
    "module": "nodenext",
    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true,

    // Environment: which globals exist
    "lib": ["es2024"],
    "types": ["node"],

    // Checking
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,

    // Keep each file transpilable on its own
    "verbatimModuleSyntax": true,
    "isolatedModules": true,

    // Speed
    "skipLibCheck": true
  },
  "include": ["src"]
}

{
  "compilerOptions": {
    "target": "es2022",
    "module": "preserve",
    "lib": ["es2022", "dom", "dom.iterable"],
    "jsx": "react-jsx",
    "noEmit": true,

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noFallthroughCasesInSwitch": true,

    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true,

    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

const names = ["Ada", "Linus"];
const third = names[2]; // default: string — with noUncheckedIndexedAccess: string | undefined

const scores: Record<string, number> = { ada: 10 };
const linus = scores["linus"]; // default: number — with the flag: number | undefined

// With the flag, these lines become errors until you handle undefined:
console.log(third.toUpperCase()); // TS18048: 'third' is possibly 'undefined'.
console.log(linus.toFixed(1)); // TS18048: 'linus' is possibly 'undefined'.

strict: true is an umbrella flag: it turns on a family of checks that make the type system honest. You can still switch individual members off ("strict": true, "strictPropertyInitialization": false), and any new strict check added in a future version is enabled automatically. Since TypeScript 6.0 strict is true by default; before that a tsconfig without it got the loose, legacy behaviour.

The most important member is strictNullChecks. Without it, null and undefined are silently part of every type: a string might be null and the checker won't mention it. With it, they're separate types that only appear where you write them (string | null), and the checker forces you to handle them before use. Accessing a property of null or undefined is the most common runtime error in JavaScript, so this one flag catches more bugs than any other.

The mental model: without strictNullChecks, every type has an invisible | null | undefined that the checker ignores. Turning it on makes that part visible — and then insists you deal with it.

let user: string | null = null;
console.log(user.toUpperCase()); // ❌ 'user' is possibly 'null'.

// The fixes, on a value that really could be either:
function shout(name: string | null): string {
  if (name !== null) {
    return name.toUpperCase(); // narrowed to string
  }
  return "ANONYMOUS";
}

function shoutMaybe(name: string | null) {
  return name?.toUpperCase(); // string | undefined — no crash
}

let user: string | null = null;
console.log(user.toUpperCase()); // ❌ 'user' is possibly 'null'.

function findUser(id: number): { name: string } | undefined {
  return id === 1 ? { name: "Rohit" } : undefined;
}
const found = findUser(2);
console.log(found.name); // ❌ 'found' is possibly 'undefined'.

let count: number = null; // ❌ Type 'null' is not assignable to type 'number'.

function double(n) { // ❌ Parameter 'n' implicitly has an 'any' type.
  return n * 2;
}

class Account {
  owner: string; // ❌ Property 'owner' has no initializer and is not definitely assigned in the constructor.
  balance = 0;
}

try {
  JSON.parse("{bad json");
} catch (err) {
  console.log(err.message); // ❌ 'err' is of type 'unknown'.
}

function greet(name: string) {
  return `Hi ${name}`;
}
greet.call(undefined, 42); // ❌ Argument of type 'number' is not assignable to parameter of type 'string'.

type Handler = (value: string | number) => void;
const onlyStrings = (value: string) => console.log(value.toUpperCase());
const handler: Handler = onlyStrings; // ❌ Type '(value: string) => void' is not assignable to type 'Handler'.

function shout() {
  return this.name.toUpperCase(); // ❌ 'this' implicitly has type 'any' because it does not have a type annotation.
}

These two options look related but control completely different things, which is why they're easy to mix up.

• target is the ECMAScript version of the syntax in the output. Any syntax newer than the target gets rewritten into older equivalents (class fields into constructor assignments, ?. and ?? into ternaries). It also picks the default lib — which built-in APIs the checker believes exist.
• module is how import/export are written in the output: kept as ES modules, turned into CommonJS require/exports, or left exactly as written for a bundler (preserve). The Node values (node16, node20, nodenext) also decide per file which format to use and which resolution rules apply.

The mental model: target answers "which language version does the engine speak?" and module answers "how do files load each other?". They're independent: ES2022 syntax in CommonJS files is perfectly normal (that's most Node code from a few years ago).

import { readFile } from "node:fs/promises";

export class Config {
  path = "./config.json";

  async load() {
    const text = await readFile(this.path, "utf8");
    return JSON.parse(text)?.port ?? 3000;
  }
}

import { readFile } from "node:fs/promises";
export class Config {
    constructor() {
        this.path = "./config.json";
    }
    async load() {
        var _a;
        var _b;
        const text = await readFile(this.path, "utf8");
        return (_b = (_a = JSON.parse(text)) === null || _a === void 0 ? void 0 : _a.port) !== null && _b !== void 0 ? _b : 3000;
    }
}

import { readFile } from "node:fs/promises";
export class Config {
    path = "./config.json";
    async load() {
        const text = await readFile(this.path, "utf8");
        return JSON.parse(text)?.port ?? 3000;
    }
}

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.Config = void 0;
const promises_1 = require("node:fs/promises");
class Config {
    path = "./config.json";
    async load() {
        const text = await (0, promises_1.readFile)(this.path, "utf8");
        return JSON.parse(text)?.port ?? 3000;
    }
}
exports.Config = Config;

import { readFile } from "node:fs/promises";
export class Config {
    path = "./config.json";
    async load() {
        const text = await readFile(this.path, "utf8");
        return JSON.parse(text)?.port ?? 3000;
    }
}

const last = [1, 2, 3].at(-1);
// with target es2019 (and no lib): TS2550: Property 'at' does not exist on type 'number[]'.
//   Do you need to change your target library? Try changing the 'lib' compiler option to 'es2022' or later.
// with target es2019 + lib [es2022, dom]: compiles, output still calls .at() — crashes on an ES2019 engine
console.log(last); // 3 on a modern runtime

const a: number | null = null;
export const port = a ?? 8080;

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.port = void 0;
const a = null;
exports.port = a ?? 8080;

Node has two module systems: CommonJS (require/module.exports) and ES modules (import/export). Node decides which one a .js file uses from the nearest package.json: "type": "module" means ESM, no "type" (or "commonjs") means CommonJS. The extensions .mjs and .cjs override that — always ESM and always CommonJS.

TypeScript mirrors this exactly. With module: "nodenext", tsc looks at the same package.json and decides each file's format the same way Node will, then emits that format and applies that format's import rules. The TypeScript extensions map one-to-one:

The mental model: under nodenext, TypeScript pretends to be Node for every file. If Node would load a file as ESM, TypeScript type-checks it as ESM — including Node's strict rule that ESM imports need full file extensions.

Take this small project with "module": "nodenext", rootDir: "src" and outDir: "dist":

// src/math.ts
export function add(a: number, b: number) { return a + b; }

// src/main.ts
import { add } from "./math";
console.log(add(1, 2));

// src/esm.mts
export const esmOnly = "from .mts";

// src/legacy.cts
export const cjsOnly = "from .cts";

// package.json has no "type"  →  dist/main.js is CommonJS
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const math_1 = require("./math");
console.log((0, math_1.add)(1, 2));

// dist/esm.mjs — ESM regardless of package.json
export const esmOnly = "from .mts";

// dist/legacy.cjs — CommonJS regardless of package.json
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.cjsOnly = void 0;
exports.cjsOnly = "from .cts";

// Now add "type": "module" to package.json and run tsc again:
src/main.ts(1,21): error TS2835: Relative import paths need explicit file extensions in ECMAScript
imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './math.js'?

import { esmOnly } from "./esm.mjs";
export const cjsOnly = "from .cts " + esmOnly;

Deep relative imports like ../../../../utils/format are hard to read and break when files move. Path aliases let you write @/utils/format instead. Historically you set baseUrl (a folder that bare imports are resolved from) and optionally paths (pattern → folder mappings).

That was the old way. TypeScript 6.0 deprecated baseUrl and TypeScript 7 removed it: the modern form is paths on its own, with targets written relative to the tsconfig file. And the direction the ecosystem is heading is to not put aliases in tsconfig at all, but in package.json "imports", which Node, bundlers and TypeScript all understand.

The single most important thing to know: paths only affects type-checking. tsc does not rewrite @/utils/format in the output. Whatever runs or bundles the code must be taught the same alias separately.

{
  "compilerOptions": {
    "baseUrl": "./src"
  }
}

$ npx tsc     # TypeScript 7
tsconfig.json(1,35): error TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.
  Use '"paths": {"*": ["./src/*"]}' instead.

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist",
    "paths": { "@/*": ["./src/*"] }
  }
}

import { x } from "@/utils/x";
console.log(x);

$ npx tsc && cat dist/main.js
import { x } from "@/utils/x";
console.log(x);

$ node dist/main.js
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/utils' imported from .../dist/main.js

{
  "type": "module",
  "imports": {
    "#src/*": "./dist/*"
  }
}

import { greet } from "#src/utils/greet.js";
console.log(greet("Rohit")); // hi Rohit

In a large repo — a monorepo, or an app with a shared library and separate test projects — compiling everything as one TypeScript program means every change re-checks everything, and nothing stops the UI code from importing server internals. Project references split the code into several smaller TypeScript projects (each with its own tsconfig) with explicit dependencies between them.

A project that others reference must set composite: true. That flag guarantees what the build system needs: it turns on declaration (so dependents read the project's .d.ts output instead of re-checking its source), turns on incremental (so a .tsbuildinfo file records what's up to date), and requires every file to be matched by include/files. Then tsc -b (build mode) walks the dependency graph, builds projects in order, and skips any whose inputs haven't changed.

If you know Gradle, the mental model is modules with declared dependencies: app depends on shared, building app builds shared first, and app only sees shared's public API (its .d.ts), not its internals.

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "rootDir": "src",
    "outDir": "dist"
  }
}

// packages/app/tsconfig.json
{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "references": [{ "path": "../shared" }]
}

// tsconfig.json (repo root): a "solution" file that only lists projects
{
  "files": [],
  "references": [{ "path": "packages/shared" }, { "path": "packages/app" }]
}

$ npx tsc -b --verbose
Projects in this build:
    * packages/shared/tsconfig.json
    * packages/app/tsconfig.json
    * tsconfig.json
Project 'packages/shared/tsconfig.json' is out of date because output file 'packages/shared/tsconfig.tsbuildinfo' does not exist
Building project 'packages/shared/tsconfig.json'...
Project 'packages/app/tsconfig.json' is out of date because output file 'packages/app/tsconfig.tsbuildinfo' does not exist
Building project 'packages/app/tsconfig.json'...

$ npx tsc -b --verbose     # again, nothing changed
Project 'packages/shared/tsconfig.json' is up to date because newest input 'packages/shared/src/index.ts' is older than output 'packages/shared/tsconfig.tsbuildinfo'
Project 'packages/app/tsconfig.json' is up to date because newest input 'packages/app/src/main.ts' is older than output 'packages/app/dist/main.js'

TypeScript can check plain JavaScript files. Its checker already infers types for JavaScript (that's what powers autocomplete in VS Code for .js files). Turning on checking makes it report errors too, and JSDoc comments let you write the types that inference can't work out — so you get most of TypeScript's safety with no build step, because the file stays valid JavaScript.

There are three switches:

• allowJs — .js files become part of the program: TypeScript files can import them with types inferred, and tsc can emit them to outDir.
• checkJs — report type errors in those .js files too (implies allowJs).
• // @ts-check at the top of one file — check just that file, even without checkJs. // @ts-nocheck opts a file out when checkJs is on.

The mental model: JSDoc is TypeScript's type syntax moved into comments. @param {Item[]} items means the same thing as items: Item[].

// @ts-check

/**
 * @typedef {Object} Item
 * @property {string} name
 * @property {number} price  Price in cents
 * @property {number} [qty]  Optional, defaults to 1
 */

/**
 * @param {Item[]} items
 * @returns {number}
 */
export function total(items) {
  return items.reduce((sum, item) => sum + item.price * (item.qty ?? 1), 0);
}

/** @type {Item} */
const coffee = { name: "Coffee", price: "450" }; // TS2322: Type 'string' is not assignable to type 'number'.

total([coffee]);
total("coffee"); // TS2345: Argument of type 'string' is not assignable to parameter of type 'Item[]'.

// @ts-check
/** @import { Item } from "./cart.js" */

/** @type {Item} */
const tea = { name: "Tea", price: 300 };

/** @satisfies {Record<string, number>} */
const prices = { tea: 300, coffee: 450 };
prices.milk; // TS2339: Property 'milk' does not exist on type '{ tea: number; coffee: number; }'.

const input = /** @type {HTMLInputElement} */ (document.querySelector("#qty"));
console.log(tea, input.value);

On a big codebase, tsc time and editor responsiveness become real problems. Most slowness comes from a few places: re-checking things that haven't changed (dependency .d.ts files, untouched projects), building enormous types (unions with tens of thousands of members, deeply recursive conditional types), and asking the checker to infer what you could have written down.

The approach is the same as any performance work: measure first, then fix the hot spot.

npx tsc --noEmit --extendedDiagnostics   # where did the time go?
npx tsc --noEmit --explainFiles          # why is each file in the program?
npx tsc --noEmit --generateTrace trace   # per-type trace for deep investigation

Files:              86
Lines:           58482
Identifiers:     49793
Symbols:         62474
Types:           37894
Instantiations:  35862
Memory used:    69060K
Parse time:     0.012s
Bind time:      0.004s
Check time:     0.112s
Total time:     0.130s

type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";

type Pin4 = `${Digit}${Digit}${Digit}${Digit}`; // 10,000 members
type Pin5 = `${Digit}${Digit}${Digit}${Digit}${Digit}`; // ❌ Expression produces a union type that is too complex to represent.

const pin: Pin4 = "0420";
console.log(pin);