@velascosoftware/next-api-router

English

Router with decorators and middlewares for the App Router Next.js (Route Handlers).
Inspired at frameworks like Spring or Nest, but simplify and adapt to the Next philosophy.

✨ Features

• ✅ Decorators to define routes (@RequestMapping)
• ✅ Middlewares at controller level (@UseController) or method level (@Use)
• ✅ Compatible with NextRequest / NextResponse from next/server
• ✅ Based on path-to-regexp for dynamic routes (/users/:id)
• ✅ Written in TypeScript with included typings
• ✅ No dependency on reflect-metadata → works out-of-the-box

📦 Installation

npm install @velascosoftware/next-api-router

Requires:

• Node.js >= 18.17
• Next.js >= 13.4

🚀 Basic Usage

1. Define your controller with decorators

import { NextRequest, NextResponse } from 'next/server';
import { RequestMapping, Use, UseController, type Middleware } from '@velascosoftware/next-api-router';

const logger: Middleware = async (req, params, next) => {
  console.log(req.method, req.nextUrl.pathname, params);
  return next();
};

@UseController(logger)
class UserController {
  @RequestMapping('/users/:id', 'GET')
  async getOne(req: NextRequest, { id }: { id: string }) {
    return NextResponse.json({ id });
  }

  @Use(async (req, params, next) => {
    console.log('Check auth');
    return next();
  })
  @RequestMapping('/users', 'POST')
  async create(req: NextRequest) {
    const body = await req.json();
    return NextResponse.json({ created: body }, { status: 201 });
  }
}

export { UserController };

2. Connect the router in your route.ts

// app/api/users/route.ts
export const runtime = 'nodejs'; //Recommended, but not neccesary

import { createNextRoute } from '@velascosoftware/next-api-router';
import { UserController } from '@/controllers/UserController';

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD } =
  createNextRoute(new UserController(), '/users');

⚡ Middlewares

A middleware is a function that receives (req, params, next) and returns a NextResponse:

import type { Middleware } from '@velascosoftware/next-api-router';

const authMiddleware: Middleware = async (req, params, next) => {
  if (!req.headers.get('authorization')) {
    return NextResponse.json({ success: false, message: 'Unauthorized' }, { status: 401 });
  }
  return next();
};

They can be applied with @UseController(...) or @Use(...) on a specific handler.

🛑 Error Handling

By default, ApiRouter catches errors and returns a 500.

📖 Exported API

// Router
export { ApiRouter, type ApiRouteController };

// Decorators
export {
  RequestMapping,
  Use,
  UseController,
  getRoutes,
  getControllerMiddlewares,
  getRouteMiddlewares,
  type RouteDefinition
};

// Types
export type { Middleware, NextHandler };

// DX Helpers
export { createNextRoute } from './next/createNextRoute';
export { createCatchAllHandlers } from './next/createCatchAllHandlers';

📂 Recommended structure

app/
  api/
    users/
      route.ts   ← mount the router here
src/
  controllers/
    UserController.ts

Español

Router con decoradores y middlewares para el App Router de Next.js (Route Handlers).
Inspirado en frameworks como Spring o Nest, pero simplificado y adaptado a la filosofía de Next.

✨ Características

• ✅ Decoradores para definir rutas (@RequestMapping)
• ✅ Middlewares a nivel controlador (@UseController) o método (@Use)
• ✅ Compatible con NextRequest / NextResponse de next/server
• ✅ Basado en path-to-regexp para rutas dinámicas (/users/:id)
• ✅ Escrito en TypeScript con tipados incluidos
• ✅ Sin dependencia de reflect-metadata → funciona out-of-the-box

📦 Instalación

npm install @velascosoftware/next-api-router

Requiere:

• Node.js >= 18.17
• Next.js >= 13.4

🚀 Uso básico

1. Define tu controlador con decoradores

import { NextRequest, NextResponse } from 'next/server';
import { RequestMapping, Use, UseController, type Middleware } from '@velascosoftware/next-api-router';

const logger: Middleware = async (req, params, next) => {
  console.log(req.method, req.nextUrl.pathname, params);
  return next();
};

@UseController(logger)
class UserController {
  @RequestMapping('/users/:id', 'GET')
  async getOne(req: NextRequest, { id }: { id: string }) {
    return NextResponse.json({ id });
  }

  @Use(async (req, params, next) => {
    console.log('Check auth');
    return next();
  })
  @RequestMapping('/users', 'POST')
  async create(req: NextRequest) {
    const body = await req.json();
    return NextResponse.json({ created: body }, { status: 201 });
  }
}

export { UserController };

2. Conecta el router en tu route.ts

// app/api/users/route.ts
export const runtime = 'nodejs'; //Recomendado, pero no necesario

import { createNextRoute } from '@velascosoftware/next-api-router';
import { UserController } from '@/controllers/UserController';

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD } =
  createNextRoute(new UserController(), '/users');

⚡ Middlewares

Un middleware es una función que recibe (req, params, next) y devuelve un NextResponse:

import type { Middleware } from '@velascosoftware/next-api-router';

const authMiddleware: Middleware = async (req, params, next) => {
  if (!req.headers.get('authorization')) {
    return NextResponse.json({ success: false, message: 'Unauthorized' }, { status: 401 });
  }
  return next();
};

Se pueden aplicar con @UseController(...) o @Use(...) en un handler específico.

🛑 Manejo de errores

Por defecto, ApiRouter atrapa errores y devuelve un 500.

📖 API Exportada

// Router
export { ApiRouter, type ApiRouteController };

// Decoradores
export {
  RequestMapping,
  Use,
  UseController,
  getRoutes,
  getControllerMiddlewares,
  getRouteMiddlewares,
  type RouteDefinition
};

// Tipos
export type { Middleware, NextHandler };

// Helpers DX
export { createNextRoute } from './next/createNextRoute';
export { createCatchAllHandlers } from './next/createCatchAllHandlers';

📂 Estructura recomendada

app/
  api/
    users/
      route.ts   ← monta el router aquí
src/
  controllers/
    UserController.ts

📜 License

MIT © 2025 Velasco Software