Stop 04 · JavaScript & TypeScript for BackendTopics · 10/12

Node.js + TypeScript Setup

In short

Before writing your first typed route, you need a project that compiles, runs and restarts properly. Ten minutes of setup now saves hours of weird errors later.

Configuring a Node.js project to write, compile and run TypeScript — `tsconfig.json`, build scripts, and choosing between compiling ahead-of-time or running directly.

The mascot arranges a gas stove, pressure cooker and utensils on a kitchen counter.

Think of it like this

Setting up a new kitchen

Before the first meal in a new flat, you fix the gas, place the cooker and hang the ladles where you can reach them. Then cooking is smooth. Setting up tsconfig, scripts and folders is the same: do it once, cook daily.

Watch it happen

A clean project layout

orders-api/

package.json

tsconfig.json

src/

index.ts

routes/

dist/

.env

1/5package.json lists dependencies and scripts: dev, build and start.

The big ideas

What you need to know

Dev dependencies

typescript, @types/node and tsx are only needed while developing, so install them with -D.

tsconfig essentials

strict on, rootDir src, outDir dist, module NodeNext for modern Node imports.

Three scripts

dev runs TypeScript directly with watch mode. build compiles to dist. start runs dist with plain node.

Load env safely

Node can read a .env file with the --env-file flag. Never hard-code keys in source files.

See it in code

Walk through the code

json

1{2  "type": "module",3  "scripts": {4    "dev": "tsx watch --env-file=.env src/index.ts",5    "build": "tsc",6    "start": "node --env-file=.env dist/index.js"7  },8  "devDependencies": {9    "@types/node": "^22.0.0",10    "tsx": "^4.0.0",11    "typescript": "^5.0.0"12  }13}

1/4Use ES Modules, so import and export work in the compiled output.

Pair this with a tsconfig.json that sets strict, rootDir "src", outDir "dist" and module "NodeNext". Run npx tsc --init to start one.

Save yourself the pain

Common mistakes

Oops

Running tsx or ts-node in production.

Do this instead

Build once with tsc and run node dist/index.js. It starts faster and doesn't need dev tools on the server.

Oops

Leaving strict off because the errors feel annoying.

Do this instead

Turn it on from day one. Switching it on later in a big project means hundreds of errors at once.

Your mission

Set up a typed API skeleton

~30 min

Quick check

Which script should a production server run?

Go deeper

1Set up a fresh Node project with TypeScript from scratch, including `tsconfig.json`.
2Configure a `build` script that compiles TS to JS for production.
3Learn the key `tsconfig.json` options: `strict`, `target`, `module`, `outDir`.