TypeScript Backend Development & Build Workflow

Project Setup

Install Dependencies

npm install tsconfig-paths
npm install -D typescript tsx @types/node nodemon cross-env

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "outDir": "dist",
    "rootDir": "src",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "incremental": true
  },
  "include": ["src"]
}

incremental: true → speeds up repeated typechecking/builds.

paths → configure @/* as alias for src/*.

package.json Scripts

"scripts": {
  "dev": "cross-env NODE_ENV=development nodemon",
  "typecheck": "tsc --noEmit --incremental",
  "prebuild": "tsc --noEmit --incremental",
  "build": "npm run prebuild && tsc",
  "start": "node dist/server.js"
}

dev → runs development server with watch & auto-restart.

typecheck → full typecheck, fast due to incremental compilation.

prebuild → typecheck before building, optional in dev, mandatory for CI/build.

build → emits production-ready JS into dist.

start → run the compiled JS in dist.

nodemon.json (for dev)

{
  "watch": ["src"],
  "ext": "ts,tsx",
  "exec": "tsx --watch -r tsconfig-paths/register src/server.ts",
  "env": {
    "NODE_ENV": "development"
  }
}

Watches src/ for .ts/.tsx changes.

Runs TS directly with path aliases resolved via tsconfig-paths.

Folder Structure Example

project/
├─ src/
│  ├─ server.ts
│  ├─ services/
│  │  └─ userService.ts
│  └─ utils/
├─ package.json
└─ tsconfig.json

Example server.ts

import Fastify from "fastify";
import { UserService } from "@/services/userService";

const app = Fastify();

app.get("/users", async () => {
  return UserService.getAll();
});

app.listen({ port: 4000 });

Recommended Workflow

Development

npm run dev

Optional: run typecheck in watch mode separately

npm run typecheck -- --watch

Fast reloads via tsx —watch.

Optional live typechecking in terminal.

CI / Production Build npm run build # runs prebuild typecheck first npm start # run compiled JS in dist/

Guarantees full type safety.

Uses incremental compilation for speed.

Best Practices

Dev: Fast reload + optional live typecheck; no need to block on full typecheck.

CI / Production: Always run typecheck before build.

Path aliases: Keep imports clean, improve maintainability.

Incremental builds: Speeds up repeated builds and typechecks.

Separation of concerns: Dev vs. build/CI workflows optimized for speed and safety.