TypeStack/routing-controllers for TypeScript: Complete Guide with Examples

\n\n

1. What It Is and Why You Need It

\n\n

TypeStack/routing-controllers is a powerful library for TypeScript that allows you to build server-side applications on Node.js using decorators. It provides a declarative way to define routes, middleware, validation, and data serialization. Instead of manually writing handlers for each HTTP request and binding them to Express or Koa, you simply annotate classes and methods with decorators, and the library automatically generates all the necessary infrastructure.

\n\n

Why is this needed? In modern web development with TypeScript, the problem of code duplication and the complexity of maintaining large projects often arises. routing-controllers solves this problem by offering a clean, modular architecture based on classes and decorators. This makes the code more readable, testable, and scalable. You can easily reuse middleware, validate incoming data using class-validator, and automatically generate OpenAPI (Swagger) documentation.

\n\n

The library integrates closely with popular frameworks such as Express and Koa and is part of the TypeStack ecosystem, which also includes class-validator, class-transformer, and typedi. This allows you to build full-fledged backend applications with dependency injection, validation, and data transformation out of the box.

\n\n

2. Installation

\n\n

To install the library and its dependencies, run the following commands in your project's terminal:

\n\n

npm install routing-controllers reflect-metadata

\n\n

You will also need to install one of the supported HTTP frameworks. Express or Koa is recommended:

\n\n

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

\n\n

Or for Koa:

\n\n

npm install koa\nnpm install @types/koa --save-dev

\n\n

Don't forget to enable experimental decorators in your tsconfig.json:

\n\n

{\n  "compilerOptions": {\n    "experimentalDecorators": true,\n    "emitDecoratorMetadata": true,\n    "target": "ES6",\n    "module": "commonjs",\n    "outDir": "./dist",\n    "rootDir": "./src",\n    "strict": true\n  }\n}

\n\n

3. Quick Start — Minimal Working Example

\n\n

Create a file app.ts with the following content:

\n\n

import 'reflect-metadata';\nimport { createExpressServer, Get, Controller, Res } from 'routing-controllers';\nimport { Response } from 'express';\n\n@Controller()\nclass UserController {\n    @Get('/users')\n    getAll(@Res() response: Response) {\n        return response.json([{ id: 1, name: 'John Doe' }]);\n    }\n}\n\nconst app = createExpressServer({\n    controllers: [UserController],\n});\n\napp.listen(3000, () => {\n    console.log('Server is running on http://localhost:3000');\n});

\n\n

Start the server with the command npx ts-node app.ts and open http://localhost:3000/users in your browser. You will see a JSON response with an array of users.

\n\n

4. Main Methods/Functions/Classes

\n\n

4.1 `@Controller`

Signature: @Controller(basePath?: string)

What it does: A class decorator that marks a class as a controller. It accepts an optional base path that will be prepended to all routes inside the class.

Working example:

@Controller('/api')\nclass ApiController {\n    @Get('/status')\n    getStatus() {\n        return { status: 'OK' };\n    }\n}\n// Route: GET /api/status

\n\n