Build Your Own Express Decorators from Scratch (Part 1)

Learn how to build your own Express decorators from scratch. A step-by-step tutorial to write cleaner, NestJS-style code in your Express apps.

expressdecoratorstypescriptclean architecturenodejs meta programmingcustom decorators expressbuild your own express decorators

02/09/2025

Decorators aren’t just for NestJS — you can bring the same power and readability to your Express apps. In this tutorial, we’ll build Express decorators from scratch, explore how they work under the hood with TypeScript, and learn how they can simplify your code while keeping it clean and maintainable.

Project Setup

To follow along, clone the demo repo (or start fresh):

git clone git@github.com:tiesen243/saciut.git

If you’re starting from scratch, here’s how to set things up.

Initialize the project
```
mkdir my-app
cd my-app
npm init -y
```
Install dependencies

We’ll use:
- cross-env - to set environment variables in scripts across platforms.
- express – the core framework.
- reflect-metadata – to enable metadata reflection for decorators.
- zod – for schema validation (for query, params, body).
- typescript – for type safety and decorators support.
- tsdown - for building TypeScript into lightweight ESM/CJS output.
```
npm install express reflect-metadata zod
npm install -D cross-env typescript tsdown @types/express @types/node
```

Configure TypeScript

Generate a tsconfig.json:

npx tsc --init

Update it to enable decorators and metadata:

tsconfig.json

{
   "compilerOptions": {
   // Other options...

   // Decorator Options
   "experimentalDecorators": true,
   "emitDecoratorMetadata": true

   // Path Aliases
   "baseUrl": ".",
     "paths": {
       "@/*": ["server/*"]
     }
   },
   "include": ["server"],
   "exclude": ["node_modules", "build", "dist"]
}

Project structure

my-app/
├── server/
│   ├── core/
│   │   ├── common/
│   │   │   ├── container.ts
│   │   │   ├── guard.ts
│   │   │   ├── http-methods.ts
│   │   │   ├── http.ts
│   │   │   ├── middleware.ts
│   │   │   ├── index.ts
│   │   │   ├── metadata.ts
│   │   │   └── params.ts
│   │   ├── create-app/
│   │   │   ├── index.ts
│   │   │   ├── parse-args.ts
│   │   │   └── register-controller.ts
│   │   ├── http.ts
│   │   └── types.d.ts
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   └── main.ts
├── package.json
├── tsconfig.json
├── tsdown.config.ts
└── ...

Build and Run Scripts

We’ll use tsdown to bundle and compile the TypeScript source into a clean dist folder. The config below handles different modes for development and production:

tsdown.config.ts

import { defineConfig } from 'tsdown'

const isDev = process.env['NODE_ENV'] === 'development'

export default defineConfig({
  entry: './server/main.ts',
  clean: true,
  shims: true,
  minify: true,
  logLevel: isDev ? 'silent' : 'info',
  onSuccess: isDev ? 'node --env-file-if-exists=.env ./dist/main.js' : ' ',
})

And in your package.json, we add scripts for each workflow:

build: compile once for production.
dev: run in watch mode with auto-rebuild + restart.
start: run the compiled app in production mode.

package.json

{
  "scripts": {
    "build": "tsdown",
    "dev": "cross-env NODE_ENV=development tsdown --watch",
    "start": "cross-env NODE_ENV=production node --env-file-if-exists=.env dist/main.js"
  }
}

Creating Core Decorators

Now that we have our project set up, let’s create the core decorators that will help us build our Express controllers in a clean and maintainable way.

Shared Types and Constants

These TypeScript types help with type inference for your Express decorators and DI system.

Type<T>: Represents a class constructor for type T.
InterRouterInpuuts<TServices>: Infers the input parameter types for each method in your service objects.
InferRouterOutputs<TControllers>: Infers the output (return) types for each method in your controller objects, unwrapping Promises if present.

server/core/types.d.ts

/* eslint-disable @typescript-eslint/no-explicit-any */

export type Type<T = any> = new (...args: any[]) => T

export type InterRouterInpuuts<TServices extends Record<string, any>> = {
  [TService in keyof TServices]: {
    [TMehod in keyof TServices[TService]]: Parameters<
      TServices[TService][TMehod]
    >
  }
}

export type InferRouterOutputs<TControllers extends Record<string, any>> = {
  [TController in keyof TControllers]: {
    [TMehod in keyof TControllers[TController]]: ReturnType<
      TControllers[TController][TMehod]
    > extends Promise<infer U>
      ? U
      : ReturnType<TControllers[TController][TMehod]>
  }
}

Module, Controller, and Injectable Decorators

Below are the core decorator implementations and their supporting metadata utilities. Each block is explained before the code.

Metadata Keys

Defines unique symbols to use as metadata keys for modules, controllers, providers, exports, and injection. These keys help store and retrieve metadata on classes and parameters.