Integrating TypeScript with Node.js

TypeScript has emerged as the preferred language for building scalable, maintainable, and robust Node.js applications. By adding static types, interfaces, and compile-time checks to JavaScript, TypeScript helps developers catch errors early and write more predictable code.

Node.js, with its asynchronous, event-driven architecture, works seamlessly with TypeScript. Developers can leverage the rich TypeScript ecosystem along with popular frameworks such as Express, NestJS, and Apollo Server to build efficient backend systems.

This article explores how to integrate TypeScript with Node.js, best practices, and examples for real-world applications.

Why Use TypeScript with Node.js

1. Type Safety

JavaScript is dynamically typed, which means errors like passing a string where a number is expected are only caught at runtime. TypeScript enforces type checking at compile time, reducing bugs.

Example:

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

add(5, '10'); // TypeScript error: Argument of type 'string' is not assignable to parameter of type 'number'

2. Improved Code Maintainability

With interfaces, types, and enums, TypeScript makes code easier to understand and maintain, especially in large applications.

3. Better Developer Experience

IDE features like auto-completion, refactoring, and inline documentation work best with TypeScript.

4. Seamless Framework Integration

Frameworks such as Express, NestJS, and Apollo Server provide official TypeScript typings, making it straightforward to build scalable backend services.

Setting Up TypeScript with Node.js

Integrating TypeScript with Node.js requires minimal setup.

Step 1: Initialize a Node.js Project

mkdir ts-node-app
cd ts-node-app
npm init -y

Step 2: Install TypeScript and Node Types

npm install typescript ts-node @types/node --save-dev

typescript: Compiler for TypeScript code.
ts-node: Executes TypeScript directly without pre-compiling.
@types/node: Type definitions for Node.js built-in modules.

Step 3: Configure tsconfig.json

npx tsc --init

Edit tsconfig.json to include recommended settings:

{
  "compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true  }
}

target: The version of JavaScript to compile to.
module: Module system, usually commonjs for Node.js.
outDir: Output directory for compiled JavaScript.
rootDir: Source TypeScript directory.
strict: Enables all strict type-checking options.
esModuleInterop: Allows default imports from CommonJS modules.

Step 4: Project Structure

ts-node-app/
 ├─ src/
 │   ├─ index.ts
 │   └─ routes/
 │       └─ userRoutes.ts
 ├─ package.json
 └─ tsconfig.json

Compiling and Running TypeScript

Compile TypeScript to JavaScript:

npx tsc

Run the compiled code:

node dist/index.js

Alternatively, use ts-node for development:

npx ts-node src/index.ts

Optional: Using nodemon with TypeScript

npm install nodemon --save-dev

Add a script to package.json:

"scripts": {
  "dev": "nodemon --watch 'src/**/*.ts' --exec 'ts-node' src/index.ts"
}

Run development server:

npm run dev

Integrating TypeScript with Express

Express is a popular web framework for Node.js. Using TypeScript improves type safety in route handlers, middleware, and request/response objects.

Step 1: Install Express and Type Definitions

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

Step 2: Create a Simple Express App in TypeScript

src/index.ts:

import express, { Request, Response } from 'express';

const app = express();
app.use(express.json());

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, TypeScript with Express!');
});

const PORT = 3000;
app.listen(PORT, () => console.log(Server running on port ${PORT}));

Request and Response types provide IntelliSense and type checking.
TypeScript ensures route handlers receive and return expected data.

Step 3: Adding Routes

src/routes/userRoutes.ts:

import { Router, Request, Response } from 'express';

const router = Router();

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

const users: User[] = [];

router.post('/users', (req: Request, res: Response) => {
  const { name, email } = req.body;
  const id = users.length + 1;
  users.push({ id, name, email });
  res.status(201).json({ id, name, email });
});

router.get('/users/:id', (req: Request, res: Response) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

export default router;

Update src/index.ts to use routes:

import userRoutes from './routes/userRoutes';

app.use('/api', userRoutes);

Integrating TypeScript with NestJS

NestJS is a Node.js framework built with TypeScript. It leverages decorators, modules, and dependency injection to simplify large-scale application development.

Step 1: Install NestJS CLI

npm install -g @nestjs/cli
nest new nest-ts-app

NestJS generates a TypeScript project structure automatically.

Step 2: Create a Module and Controller

nest generate module users
nest generate controller users
nest generate service users

users.controller.ts:

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { UsersService } from './users.service';
import { User } from './user.interface';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() user: User) {
return this.usersService.create(user);  }

  @Get(':id')
  findOne(@Param('id') id: string) {
return this.usersService.findOne(Number(id));  }
}

users.service.ts:

import { Injectable } from '@nestjs/common';
import { User } from './user.interface';

@Injectable()
export class UsersService {
  private users: User[] = [];

  create(user: User): User {
user.id = this.users.length + 1;
this.users.push(user);
return user;  }

  findOne(id: number): User | undefined {
return this.users.find(u =&gt; u.id === id);  }
}

user.interface.ts:

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

NestJS enforces TypeScript throughout the project.
Controllers, services, and interfaces provide strong type checking.

Integrating TypeScript with Apollo Server

Apollo Server enables GraphQL APIs in Node.js. TypeScript enhances type safety for schemas, resolvers, and context.

Step 1: Install Dependencies

npm install apollo-server graphql
npm install @types/node --save-dev

Step 2: Define a GraphQL Schema

src/schema.ts:

import { gql } from 'apollo-server';

export const typeDefs = gql`
  type User {
id: ID!
name: String!
email: String!  }

  type Query {
users: &#91;User!]!
user(id: ID!): User  }

  type Mutation {
createUser(name: String!, email: String!): User!  }
`;

Step 3: Implement Resolvers in TypeScript

src/resolvers.ts:

import { User } from './types';

const users: User[] = [];

export const resolvers = {
  Query: {
users: () =&gt; users,
user: (_: any, { id }: { id: number }) =&gt; users.find(u =&gt; u.id === id)  },
  Mutation: {
createUser: (_: any, { name, email }: { name: string, email: string }) =&gt; {
  const id = users.length + 1;
  const newUser: User = { id, name, email };
  users.push(newUser);
  return newUser;
}  }
};

src/types.ts:

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

Step 4: Start Apollo Server