TypeScript on Node

On the backend, TypeScript earns its keep even more than in the browser: request bodies, database rows, configuration and third-party responses all pass through your code, and a type error in a rarely used path can sit undetected until it takes down production. This lesson sets up a TypeScript Node project the modern way: Node runs .ts files directly, the compiler checks types, and a build step produces plain JavaScript for production. It assumes you know TypeScript's syntax from the frontend roadmap's TypeScript essentials lesson.

#Creating the project

mkdir orders-api && cd orders-api
npm init -y
npm pkg set type=module
npm install --save-dev typescript @types/node
mkdir src

• "type": "module" makes .js files ES modules.
• typescript provides tsc, the type checker and compiler.
• @types/node provides types for Node's built-in modules, so process.env and node:fs are typed.

#Running TypeScript directly

Since Node 22.18 (and 23.6), Node runs .ts files natively through type stripping: it erases the type annotations and runs the JavaScript that's left, with no compile step.

// src/hello.ts
type Greeting = { name: string; excited?: boolean }

function greet({ name, excited = false }: Greeting): string {
  return `Hello, ${name}${excited ? '!' : '.'}`
}

console.log(greet({ name: 'Ana', excited: true }))

node src/hello.ts

Hello, Ana!

Two limits to know:

1. Node doesn't check types. greet({ name: 42 }) runs happily. Type checking is a separate step with tsc (below), run in your editor and in CI.
2. Only erasable syntax works. Type stripping can delete annotations, but can't rewrite code. TypeScript features that generate JavaScript are rejected: enum, namespace, and constructor parameter properties (constructor(private db: Db)). Use union types and objects instead of enums:

// Instead of: enum Status { Pending, Paid }
export const Status = { Pending: 'pending', Paid: 'paid' } as const
export type Status = (typeof Status)[keyof typeof Status] // 'pending' | 'paid'

The erasableSyntaxOnly compiler option (TypeScript 5.8+) makes tsc flag these features for you.

Alternatives exist if you're on an older Node or need non-erasable syntax: tsx (npx tsx src/server.ts) runs any TypeScript with esbuild. Both approaches skip type checking at run time.

#tsconfig.json for Node

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "es2023",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["es2023"],
    "types": ["node"],

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,

    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,

    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

What the important options do:

That last pair needs a word. In ES modules, relative imports must include the file extension. When Node runs your source directly, the file really is db.ts, so you write:

import { db } from './db.ts'
import type { Order } from './types.ts'

and the compiled output in dist/ imports ./db.js.

#Type-checking and building

Add scripts to package.json:

{
  "scripts": {
    "dev": "node --watch --env-file=.env src/server.ts",
    "typecheck": "tsc --noEmit",
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

• npm run dev runs the source directly, restarting on every change, with variables from .env.
• npm run typecheck checks every file without writing output. Run it in CI on every pull request; your editor runs the same checks as you type.
• npm run build compiles src/ to JavaScript in dist/, with source maps so stack traces point at your .ts lines.
• npm start runs the compiled output, which is what production runs.

Why build for production when Node can run .ts? A build fails loudly on type errors before deploy, the output starts slightly faster, and production images then don't need TypeScript at all. Some teams do run .ts directly in production; if you do, make npm run typecheck a required CI step.

#Typing the boundaries

TypeScript only knows what you tell it. Inside your code, types flow automatically; at the boundaries, where data enters from outside, it has no idea what's really there:

const port = process.env.PORT            // string | undefined
const body = await request.json()        // any (or unknown)
const rows = await db.query('SELECT ...') // whatever the driver claims

process.env.PORT is string | undefined, never a number. A JSON body is untyped until something checks it. A type annotation on such values is a claim, not a check:

const order = (await request.json()) as Order // compiles, but nothing verified it

The rest of this roadmap validates every boundary at runtime with Zod schemas, which produce TypeScript types from the same definition, so the claim and the check can't disagree. Configuration is the first boundary, and validating it at startup turns "undefined is not a function" in the middle of the night into a clear error at deploy time:

// src/config.ts
import { z } from 'zod'

const Env = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.url(),
})

export const config = Env.parse(process.env)
export type Config = z.infer<typeof Env>

z.coerce.number() converts the string from the environment, and Env.parse throws at startup, listing every missing or invalid variable, before the server accepts a single request.

#Project layout

A layout that scales from a small API to a large one:

orders-api/
  package.json
  package-lock.json
  tsconfig.json
  .env.example          # documents required variables (no secrets); .env is in .gitignore
  src/
    server.ts           # entry point: starts listening, handles shutdown
    app.ts              # builds the app (routes, middleware), with no side effects; tests import it
    config.ts
    db.ts
    orders/
      routes.ts
      service.ts
      repository.ts
      schemas.ts
  test/
  dist/                 # build output, in .gitignore

Group code by feature (orders/, users/), not by technical layer (controllers/, models/), so a change to orders stays in one folder. Keep app.ts free of side effects such as listening on a port: tests then import the app and send it requests without starting a server.

#Practice

Set up the orders-api project from this lesson:

1. Create the project with the package.json settings, scripts and tsconfig.json above, and install zod.
2. Add src/config.ts as shown, and a src/server.ts that imports the config and logs listening on port <PORT> in <NODE_ENV> mode (no real server yet).
3. Create .env with DATABASE_URL=postgres://localhost/orders and run npm run dev. Then remove DATABASE_URL and check that startup fails with a readable error.
4. Add a file using an enum and see what npm run typecheck and node say. Replace it with an as const object.
5. Run npm run build and npm start, and check that dist/ contains .js files whose imports end in .js.

// src/server.ts
import { config } from './config.ts'

console.log(`listening on port ${config.PORT} in ${config.NODE_ENV} mode`)

echo 'DATABASE_URL=postgres://localhost/orders' > .env
npm run dev
# listening on port 3000 in development mode

ZodError: [
  {
    "expected": "string",
    "code": "invalid_type",
    "path": ["DATABASE_URL"],
    "message": "Invalid input: expected string, received undefined"
  }
]

src/status.ts:1:13 - error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.

#Key takeaways

• Node 22.18+ runs .ts files directly by stripping types, but doesn't check them; run tsc --noEmit in your editor and CI.
• Type stripping supports only erasable syntax: use as const objects and unions instead of enum, and set erasableSyntaxOnly.
• Use module: nodenext, strict, noUncheckedIndexedAccess, verbatimModuleSyntax, and .ts import extensions rewritten at build time.
• Build to dist/ for production with source maps enabled; commit the lock file and keep .env out of Git.
• Types are claims at the boundaries: validate environment variables, request bodies and external data at runtime with Zod.