Node.js

Node.js with TypeScript 🟢🔷

1. Introduction 👋

TypeScript is a statically typed superset of JavaScript that compiles down to plain JavaScript. When paired with Node.js, it gives backend developers compile-time safety, better tooling, and a smoother developer experience. This tutorial walks through everything from initial setup to advanced typing patterns, build pipelines, and production best practices.

Information

This tutorial assumes basic familiarity with JavaScript and the command line, but no prior TypeScript experience is required.

2. Why Use TypeScript with Node.js? 🤔

Node.js applications can grow large and complex quickly. TypeScript helps catch bugs before runtime by enforcing types across your codebase.

Static type checking — catches type errors at compile time, not in production.
Better editor support — autocompletion, inline docs, and refactoring tools via tsserver.
Self-documenting code — types act as living documentation for functions and modules.
Safer refactors — the compiler flags breakages across the codebase instantly.
Ecosystem support — most popular packages ship with or have community @types definitions.

Aspect	JavaScript	TypeScript
Type checking	None (runtime only)	Compile-time static checks
Tooling	Basic	RichIntelliSense & refactoring
Learning curve	Lower	Slightly higher
Build step	Not required	Required (tsc or bundler)

3. Project Setup 🏗️

Start by initializing a new Node.js project and installing TypeScript as a development dependency.

Terminal

mkdir my-ts-app && cd my-ts-app
npm init -y
npm install typescript @types/node --save-dev
npx tsc --init

This creates a package.json and a base tsconfig.json. A typical starting structure looks like this:

my-ts-app

package.json

tsconfig.json

src

index.ts

dist

Tip

Add a "start": "node dist/index.js" and "build": "tsc" script to package.json for convenience.

4. TypeScript Configuration ⚙️

The tsconfig.json file controls how TypeScript compiles your code. Below is a solid baseline for a Node.js backend project.

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Option	Purpose
strict	Enables all strict type-checking flags at once.
target	The output JavaScript version.
module	The module system used in emitted code.
outDir / rootDir	Where compiled files go vs. where source lives.

Important

Always enable strict mode on new projects — retrofitting it later is much harder.

5. ES Modules 📦

ES Modules (import/export) are the modern JavaScript standard and TypeScript's preferred module format.

src/math.ts

export function add(a: number, b: number): number {
  return a + b;
}

export default class Calculator {
  multiply(a: number, b: number): number {
    return a * b;
  }
}

src/index.ts

import Calculator, { add } from "./math.js";

const calc = new Calculator();
console.log(add(2, 3), calc.multiply(2, 3));

Warning

When using NodeNext module resolution, relative imports MUST include the .js extension, even in .ts files.

6. CommonJS 🧩

CommonJS (require/module.exports) is Node's original module system and is still widely used in older codebases.

src/math.cts

function add(a: number, b: number): number {
  return a + b;
}

module.exports = { add };

src/index.cts

const { add } = require("./math.cjs");
console.log(add(4, 5));

Note

You can mix ESM and CJS in a single project using file extensions .mts and .cts, but it requires careful configuration.

7. Module Resolution 🧭

Module resolution determines how TypeScript locates the files behind an import statement. Choosing the wrong strategy is a common source of confusing errors.

Strategy	Best For
NodeNext	Modern Node.js projects mixing ESM/CJS.
Node10 (legacy Node)	Older CommonJS-only projects.
Bundler	Projects using Webpack, esbuild, or Vite.

import "./utils.js"

Is it a relative path?

Yes → resolve exact file

No → is it a package?

Check "exports" field

Fallback to "main"/"types"

8. Path Aliases 🛣️

Path aliases let you replace long relative imports like ../../../utils with clean, absolute-style paths.

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@utils/*": ["src/utils/*"],
      "@models/*": ["src/models/*"]
    }
  }
}

src/index.ts

import { formatDate } from "@utils/date.js";

Caution

Path aliases are a compile-time only feature. At runtime, Node.js won't understand them unless you use a resolver like tsc-alias or a bundler.

9. Typing Environment Variables 🔐

By default, process.env values are typed as string | undefined. You can extend this with declaration merging.

src/env.d.ts

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: "development" | "production" | "test";
      DATABASE_URL: string;
      PORT?: string;
    }
  }
}

export {};

Tip

Consider validating environment variables at runtime too (e.g. with zod), since types alone don't guarantee the values actually exist.

10. Typing Configuration 🧾

Application configuration objects benefit greatly from explicit interfaces, especially when loaded from JSON or YAML.

src/config.ts

interface AppConfig {
  port: number;
  db: {
    host: string;
    name: string;
  };
  features: Record<string, boolean>;
}

const config: AppConfig = {
  port: Number(process.env.PORT ?? 3000),
  db: { host: "localhost", name: "mydb" },
  features: { betaSearch: true },
};

export default config;

11. Typing File System Operations 📁

Node's fs/promises module is fully typed out of the box thanks to @types/node.

src/files.ts

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

async function readConfig(path: string): Promise<Record<string, unknown>> {
  const raw: string = await readFile(path, "utf-8");
  return JSON.parse(raw);
}

async function saveLog(path: string, message: string): Promise<void> {
  await writeFile(path, message, { flag: "a" });
}

Hint

Prefer unknown over any for parsed JSON — it forces you to validate the shape before use.

12. Typing HTTP Servers 🌐

The built-in http module provides types for requests, responses, and servers.

src/server.ts

import { createServer, IncomingMessage, ServerResponse } from "node:http";

const server = createServer((req: IncomingMessage, res: ServerResponse) => {
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ message: "Hello, TypeScript!" }));
});

server.listen(3000, () => console.log("Server running on port 3000 🚀"));

Information

Frameworks like Express or Fastify provide their own richer request/response types via @types/express or built-in typings.

13. Typing APIs 🔌

Typing your API layer end-to-end (requests, responses, and route handlers) reduces bugs between frontend and backend.

src/routes/users.ts

import { Request, Response } from "express";

interface CreateUserBody {
  name: string;
  email: string;
}

interface UserResponse {
  id: string;
  name: string;
  email: string;
}

export function createUser(
  req: Request<{}, {}, CreateUserBody>,
  res: Response<UserResponse>
): void {
  const { name, email } = req.body;
  res.status(201).json({ id: "u_123", name, email });
}

Generic Slot	Meaning
1st ({})	Route params
2nd ({})	Response body override
3rd (CreateUserBody)	Request body shape

14. Typing Database Operations 🗄️

Modern ORMs like Prisma or Drizzle generate types automatically from your schema, giving you full autocomplete on queries.

src/db.ts

import { PrismaClient, User } from "@prisma/client";

const prisma = new PrismaClient();

async function getUserById(id: string): Promise<User | null> {
  return prisma.user.findUnique({ where: { id } });
}

Best Practice

Avoid manually re-declaring database row types — let your ORM generate them so schema and types never drift apart.

15. Typing Events 📡

Node's EventEmitter can be strongly typed so listeners and emitted events always match.

src/emitter.ts

import { EventEmitter } from "node:events";

interface Events {
  userCreated: [id: string, name: string];
  error: [error: Error];
}

class TypedEmitter extends EventEmitter {
  emit<K extends keyof Events>(event: K, ...args: Events[K]): boolean {
    return super.emit(event, ...args);
  }
  on<K extends keyof Events>(event: K, listener: (...args: Events[K]) => void): this {
    return super.on(event, listener as (...args: any[]) => void);
  }
}

const bus = new TypedEmitter();
bus.on("userCreated", (id, name) => console.log(id, name));

16. Typing Streams 🌊

Streams are typed via generics on Readable, Writable, and Transform.

src/stream.ts

import { Transform, TransformCallback } from "node:stream";

class UpperCaseTransform extends Transform {
  _transform(chunk: Buffer, _enc: BufferEncoding, callback: TransformCallback): void {
    callback(null, chunk.toString().toUpperCase());
  }
}

process.stdin.pipe(new UpperCaseTransform()).pipe(process.stdout);

17. Typing Worker Threads 🧵

Worker threads let you run CPU-intensive tasks off the main thread. Messages passed between threads can be typed explicitly.

src/worker.ts

import { parentPort, workerData } from "node:worker_threads";

interface WorkerInput { numbers: number[]; }
interface WorkerOutput { sum: number; }

const input = workerData as WorkerInput;
const result: WorkerOutput = { sum: input.numbers.reduce((a, b) => a + b, 0) };

parentPort?.postMessage(result);

Caution

workerData is typed as any by default — always cast it to a known interface before use.

18. Typing Third-Party Packages 📚

Most popular packages either ship their own types or have community-maintained ones under the @types scope on DefinitelyTyped.

Terminal

npm install lodash
npm install @types/lodash --save-dev

Warning

If no types exist for a package, TypeScript will flag an implicit any error under strict mode unless you add a manual declaration.

19. Declaration Files 📄

Declaration files (.d.ts) describe the shape of JavaScript code without providing an implementation — useful for untyped packages or global augmentations.

src/types/legacy-lib.d.ts

declare module "legacy-lib" {
  export function doSomething(input: string): number;
  export const version: string;
}

Reference

Declaration files are also how libraries publish types alongside their compiled JavaScript in a dist/*.d.ts folder.

20. Build Process 🔨

The TypeScript compiler (tsc) transforms .ts files into plain .js ready for Node to execute.

Terminal

npx tsc

A typical build produces a mirrored output directory:

dist

index.js

index.js.map

index.d.ts

src/*.ts

tsc (type-check + emit)

dist/*.js

21. Development Workflow 🛠️

A smooth dev loop typically uses a watcher and auto-restarter instead of manually rebuilding on every change.

✍️

Write TypeScript code in src/.

👀

Run tsx watch or ts-node-dev to auto-reload on save.

🐞

Fix type errors surfaced instantly in the editor.

✅

Run tests with vitest or jest.

📦

Commit and push once everything passes.

Terminal

npm install tsx --save-dev
npx tsx watch src/index.ts

22. Production Builds 📦

Production builds should be optimized, minimal, and free of development-only tooling.

Run tsc (or a bundler like esbuild) to compile src/ into dist/.
Strip source maps and comments if bundle size matters.
Copy non-TS assets (e.g. .json, .env.example) into dist/ manually.
Run node dist/index.js as the production start command.

package.json (scripts)

{
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/index.js"
  }
}

23. Performance Considerations ⚡

Use isolatedModules and modern bundlers (esbuild, swc) for much faster builds than plain tsc.
Enable incremental compilation to speed up repeated builds.
Avoid overly complex conditional/generic types — they can slow down the type checker itself.
Use skipLibCheck to avoid re-checking types inside node_modules.

Tip

TypeScript's type checking happens at build time, so it has zero runtime performance cost on its own.

24. Best Practices ✅

Always enable strict mode from day one.
Prefer unknown over any when the type is genuinely uncertain.
Validate external data (env vars, API responses, file contents) at runtime, not just compile time.
Keep types close to the code they describe; avoid one giant types.ts file.
Use path aliases sparingly and consistently across the project.

Best Practice

Treat tsc --noEmit as a required CI step — it catches type errors before they ever reach production.

25. Common Mistakes ⚠️

Mistake	Why It's a Problem
Using any everywhere	Defeats the entire purpose of TypeScript.
Skipping strict mode	Misses many real bugs the compiler could catch.
Forgetting .js extensions in ESM imports	Causes ERR_MODULE_NOT_FOUND at runtime.
Mismatched module/moduleResolution	Leads to confusing resolution errors.
Not typing process.env	Silent undefined bugs in production.

26. Frequently Asked Questions ❓

Question

Do I need TypeScript to use Node.js effectively?

Answer

No — Node.js works fine with plain JavaScript. TypeScript is an optional layer that adds safety and tooling.

Question

Can I run .ts files directly without compiling?

Answer

Yes, using tools like tsx or Node's experimental native TypeScript support in recent versions, though production builds still typically compile ahead of time.

Question

Why do relative imports need a .js extension in .ts files?

Answer

Because Node's ESM loader resolves imports based on the final compiled output, not the TypeScript source.

Question

Should I use CommonJS or ES Modules for new projects?

Answer

ES Modules — they're the modern standard and better supported by the current tooling ecosystem.

27. Summary 📋

TypeScript brings type safety, better tooling, and long-term maintainability to Node.js applications. From project setup and configuration to typing HTTP servers, databases, streams, and worker threads, a well-typed Node.js codebase catches entire classes of bugs before they ever run.

Set up tsconfig.json with strict mode enabled.
Choose ESM or CommonJS deliberately and configure module resolution accordingly.
Type environment variables, configs, APIs, and database access explicitly.
Use a fast dev workflow (tsx watch) and a clean production build (tsc).
Follow best practices and avoid any wherever possible.

Summary

With the right setup, TypeScript and Node.js form a robust, scalable foundation for building modern backend applications. 🎉

1. Introduction 👋

ℹ️Information

2. Why Use TypeScript with Node.js? 🤔

3. Project Setup 🏗️

Terminal

💡Tip

4. TypeScript Configuration ⚙️

tsconfig.json

❗Important

5. ES Modules 📦

src/math.ts

src/index.ts

⚠️Warning

6. CommonJS 🧩

src/math.cts

src/index.cts

📝Note

7. Module Resolution 🧭

8. Path Aliases 🛣️

tsconfig.json

src/index.ts

🟡Caution

9. Typing Environment Variables 🔐

src/env.d.ts

💡Tip

10. Typing Configuration 🧾

src/config.ts

11. Typing File System Operations 📁

src/files.ts

🔍Hint

12. Typing HTTP Servers 🌐

src/server.ts

ℹ️Information

13. Typing APIs 🔌

src/routes/users.ts

14. Typing Database Operations 🗄️

src/db.ts

⭐Best Practice

15. Typing Events 📡

src/emitter.ts

16. Typing Streams 🌊

src/stream.ts

17. Typing Worker Threads 🧵

src/worker.ts

🟡Caution

18. Typing Third-Party Packages 📚

Terminal

⚠️Warning

19. Declaration Files 📄

src/types/legacy-lib.d.ts

🔗Reference

20. Build Process 🔨

Terminal

21. Development Workflow 🛠️

Terminal

22. Production Builds 📦

package.json (scripts)

23. Performance Considerations ⚡

💡Tip

24. Best Practices ✅

⭐Best Practice

25. Common Mistakes ⚠️

26. Frequently Asked Questions ❓

❓Question

💬Answer

❓Question

💬Answer

❓Question

💬Answer

❓Question

💬Answer

27. Summary 📋

📋Summary

Information

Tip

Important

Warning

Note

Caution

Tip

Hint

Information

Best Practice

Caution

Warning

Reference

Tip

Best Practice

Question

Answer

Question

Answer

Question

Answer

Question

Answer

Summary