Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ import { Server } from 'typescript-rest';
✗ import Server from 'typescript-rest';
The primary entry point for registering decorated service classes with an Express application. It is a named export, not a default export.
Path
✓ import { Path, GET, PathParam } from 'typescript-rest';
✗ const Path = require('typescript-rest').Path;
Decorators like `Path`, `GET`, `POST`, `PathParam`, etc., are named exports. Ensure TypeScript compiler options `experimentalDecorators` and `emitDecoratorMetadata` are set to `true`.
express.Application
✓ import * as express from 'express';
✗ import express from 'express';
While `import express from 'express';` often works with `esModuleInterop: true`, `import * as express from 'express';` is a more robust import style for the Express module in TypeScript projects to correctly handle its CommonJS export structure.
Demonstrates defining a simple REST endpoint using decorators (`@Path`, `@GET`, `@PathParam`) and integrating it with an Express application.
import * as express from "express";
import { Server, Path, GET, PathParam } from "typescript-rest";
// Ensure you have 'npm install reflect-metadata' and import it once globally if using IoC/complex types with decorators:
// import 'reflect-metadata';
@Path("/hello")
class HelloService {
@Path(":name")
@GET
sayHello( @PathParam('name') name: string ): string {
return "Hello " + name;
}
}
let app: express.Application = express();
// Build and register all decorated services with the Express app
Server.buildServices(app);
app.listen(3000, function() {
console.log('typescript-rest server listening on port 3000!');
console.log('Try: GET http://localhost:3000/hello/john_doe');
});
Debug
Known issues
breakingUpgrading from `typescript-rest` v2.x to v3.x may introduce breaking changes. Always consult the official changelog or migration guide before a major version upgrade to understand specific API changes.fixReview the project's GitHub releases and Wiki for detailed migration instructions and API changes between major versions.
affects: >=3.0.0
gotchaTypeScript's experimental decorators (`experimentalDecorators: true` in tsconfig.json) are required for `typescript-rest` to function. Additionally, `emitDecoratorMetadata: true` and `reflect-metadata` (imported once globally) are essential for advanced features like dependency injection and proper type reflection.fixAdd `"experimentalDecorators": true, "emitDecoratorMetadata": true` to your `compilerOptions` in `tsconfig.json`. Install `reflect-metadata` (`npm install reflect-metadata`) and import it once at your application's entry point (`import 'reflect-metadata';`).
affects: >=1.0.0
gotchaTypeScript 5.0 introduced a new, standardized decorators implementation. `typescript-rest` currently relies on TypeScript's 'legacy' or 'experimental' decorators. Mixing these with native TS 5+ decorators or failing to configure `tsconfig.json` correctly for legacy decorators can lead to unexpected behavior or compilation errors.fixEnsure your `tsconfig.json` explicitly enables `experimentalDecorators: true`. If targeting Node.js, `"target": "es6"` or newer is recommended. Be aware that the `experimentalDecorators` flag will eventually be deprecated by TypeScript, potentially requiring future migration.
affects: >=5.0.0 of TypeScript
gotchaError handling in `typescript-rest` relies on Express.js middleware. Custom error handling middleware should be registered *after* `Server.buildServices(app)` to catch errors thrown by the REST services. Incorrect ordering can result in unhandled exceptions or generic 500 responses.fixImplement custom error handling middleware in Express, ensuring it's defined and registered after `Server.buildServices(app)` in your application setup. Example: `app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => { /* handle error */ });` affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: Reflect is not defined
The `reflect-metadata` polyfill was not loaded, which is required by TypeScript's `emitDecoratorMetadata` feature.
fixInstall `reflect-metadata` (`npm install reflect-metadata`) and add `import 'reflect-metadata';` once at the very top of your application's entry file (e.g., `server.ts` or `app.ts`).
Decorator '...' is not a valid decorator factory.
The TypeScript compiler option `experimentalDecorators` is not enabled, preventing the use of decorator syntax.
fixIn your `tsconfig.json`, add `"experimentalDecorators": true` to the `compilerOptions` section.
Error: Can't set headers after they are sent to the client.
This is a common Express.js error, often occurring when an asynchronous operation or error handler attempts to send a response after one has already been sent (e.g., by a decorator, another middleware, or a prior `res.send`/`res.json` call).
fixEnsure that your API methods and middleware handle responses exactly once. For asynchronous operations, ensure you `await` promises. If using custom error handlers, make sure they only attempt to send a response if one hasn't already been sent, or pass control to the next error handler using `next(err)`.
Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
This TypeScript error often occurs when a decorated parameter (e.g., `@QueryParam('id') id: string`) might implicitly be `undefined` or `null` if the client doesn't provide it, but the method parameter expects a non-nullable type.
fixMake the parameter type explicit to allow `undefined` or provide a default value. For example, change `id: string` to `id?: string` or `id: string = 'default_value'`.
Audit
Dependencies
expressrequiredCore web server framework extended by typescript-rest. Required at runtime.
typescriptrequiredRequired for compiling TypeScript code, especially for decorator support. Development dependency.
reflect-metadatarequiredRequired when `emitDecoratorMetadata` is enabled in `tsconfig.json` for decorator metadata reflection. Required at runtime.
typescript-iocoptionalOptional peer dependency for using `typescript-ioc` as an Inversion of Control container for dependency injection.
typescript-rest-iocoptionalOptional peer dependency; provides the service factory to integrate `typescript-rest` with `typescript-ioc`.