The API: list, get one, create​

Both versions expose:

• GET /api/posts — list posts
• GET /api/posts/:id — get one post
• POST /api/posts — create a post, with title/content validation

Plain route handlers​

Two files, one per route segment, because that's how App Router file-based routing works:

import {NextRequest, NextResponse} from "next/server";
import {db} from "@/lib/db";

export async function GET() {
  const posts = await db.post.findMany();
  return NextResponse.json(posts);
}

export async function POST(request: NextRequest) {
  const body = await request.json();

  if (typeof body.title !== "string" || body.title.length === 0) {
    return NextResponse.json({message: "title is required"}, {status: 400});
  }
  if (typeof body.content !== "string") {
    return NextResponse.json({message: "content is required"}, {status: 400});
  }

  const post = await db.post.create({data: {title: body.title, content: body.content}});
  return NextResponse.json(post, {status: 201});
}

import {NextRequest, NextResponse} from "next/server";
import {db} from "@/lib/db";

export async function GET(
  _request: NextRequest,
  {params}: {params: Promise<{id: string}>}
) {
  const {id} = await params;
  const post = await db.post.findUnique({where: {id}});

  if (!post) {
    return NextResponse.json({message: "Not Found"}, {status: 404});
  }

  return NextResponse.json(post);
}

Nothing here is wrong, exactly — but look at what's already crept in with just three routes:

• Validation is hand-rolled, inline, and ad hoc. title gets a length check; content doesn't. Nobody decided that on purpose — it's just what got typed.
• The "not found" response shape ({message: "Not Found"}) has to be remembered and retyped in every route that needs it. A fourth route will either copy-paste it or quietly return something slightly different.
• There is no single place that lists "every route this API has." You reconstruct it by browsing the app/api folder tree.

None of that is a problem at three routes. It's the shape of the problem at thirty.

The same API with nextjs-nestapi​

import {IsString, MinLength} from "class-validator";

export class CreatePostDto {
  @IsString()
  @MinLength(1)
  title!: string;

  @IsString()
  content!: string;
}

import {Controller, Get, Post, Body, type RouteContext} from "nextjs-nestapi";
import {CreatePostDto} from "./dto";
import {db} from "@/lib/db";

@Controller("/posts")
export class PostController {
  @Get("")
  async list() {
    return db.post.findMany();
  }

  @Get("/:id")
  async getOne(context: RouteContext) {
    const post = await db.post.findUnique({where: {id: context.params.id}});
    if (!post) {
      return context.json({message: "Not Found"}, {status: 404});
    }
    return post;
  }

  @Post("")
  async create(@Body(CreatePostDto) dto: CreatePostDto) {
    return db.post.create({data: dto});
  }
}

Registered once in app.ts, dispatched through the one catch-all route every controller shares — see the Quick start if you haven't wired that up yet.

The POST handler here has no validation code in it at all. @Body(CreatePostDto) parses the request body, runs it against the DTO's class-validator decorators, and either injects a validated CreatePostDto instance or short-circuits with a structured 422-shaped error — before create() ever runs:

{
  "success": false,
  "message": "Validation failed",
  "errors": [{"field": "title", "message": "title should not be empty"}]
}

content is validated too, because leaving a field unvalidated now takes a deliberate choice — deleting a decorator — rather than just not getting around to writing a check.

Side by side​

When plain route handlers are still the right call​

This isn't a "always use a framework" post. Reach for plain route handlers when:

• It's one or two endpoints. A webhook receiver or a health check doesn't need a controller class for one function.
• You want the file tree to be the route map. Some teams specifically like that app/api/posts/[id]/route.ts tells you the URL just by existing. nextjs-nestapi trades that for decorator-based organization behind a single catch-all route.
• You're validating nothing, or almost nothing. If a route has no request body worth validating, @Body() isn't buying you anything.

And the reverse: reach for nextjs-nestapi once you notice the same validation boilerplate, the same error shape, and the same "which file was that route in again?" friction showing up more than once. That's the point where a few decorators pay for themselves.

Try it​

npx nextjs-nestapi new my-app

Then walk through the Quick start, or read how DTO validation actually works under the hood.

Starting a brand new project​

npx nextjs-nestapi new my-app

This runs create-next-app under the hood, then:

• writes src/app.ts with an empty createApplication({ controllers: [] })
• writes src/app/api/[[...route]]/route.ts, the catch-all dispatcher
• patches tsconfig.json with experimentalDecorators/emitDecoratorMetadata
• installs nextjs-nestapi, class-validator, and class-transformer

Add --swagger to also scaffold /api/openapi.json and /api-docs (see the OpenAPI / Swagger docs post).

Wiring an existing project​

Already have a Next.js App Router project? init does the same wiring without the create-next-app step:

npx nextjs-nestapi init --swagger

It never overwrites a file that already exists unless you pass --force, and if it can't patch tsconfig.json automatically (say, because compilerOptions isn't where it expects), it tells you exactly what to add by hand instead of guessing.

Adding a feature​

npx nextjs-nestapi generate controller student
# or the short alias:
npx nextjs-nestapi g controller student

This scaffolds:

src/features/student/controller.ts
src/features/student/dto.ts

and, if src/app.ts has a recognizable controllers: [...] array, registers StudentController there automatically — import added, array updated. If the shape of app.ts isn't recognized, the command leaves it untouched and prints what to add yourself, rather than risk corrupting a file it can't parse confidently.

Full reference: CLI.

Install the two extra pieces​

npm install class-validator-jsonschema swagger-ui-dist

• class-validator-jsonschema turns your class-validator DTOs into JSON Schema.
• swagger-ui-dist ships the actual Swagger UI assets — served straight from your own node_modules, not vendored in the library and not pulled from a CDN.

Optional: annotate for nicer docs​

Routes are documented either way; @ApiTags/@ApiOperation/@ApiResponse just add human-readable metadata:

import {Controller, Post, Body, ApiTags, ApiOperation, ApiResponse} from "nextjs-nestapi";

@ApiTags("Hello")
@Controller("/hello")
export class HelloController {
  @ApiOperation({summary: "Create a hello"})
  @ApiResponse({status: 200, description: "Created"})
  @Post("")
  create(@Body(CreateHelloDto) dto: CreateHelloDto) {
    return {created: dto};
  }
}

Expose the document and the UI​

import {NextResponse} from "next/server";
import {generateOpenApiDocument} from "nextjs-nestapi";
import "@/app"; // populates the decorator registries

export async function GET() {
  return NextResponse.json(generateOpenApiDocument({title: "My API"}));
}

import {createSwaggerUiHandler} from "nextjs-nestapi";

export const GET = createSwaggerUiHandler({openApiUrl: "/api/openapi.json"});

The one config flag you need​

createSwaggerUiHandler resolves swagger-ui-dist with a dynamic import() at request time. Turbopack and webpack both try to bundle that call by default and fail — mark the package external and it resolves correctly:

const nextConfig: NextConfig = {
  serverExternalPackages: ["swagger-ui-dist"],
};

Skip this and the Swagger UI's static assets (swagger-ui-bundle.js, swagger-ui.css) will 404.

That's it — visit /api-docs for the UI, /api/openapi.json for the raw spec. Full reference: OpenAPI / Swagger docs.

NestJS solves exactly this with controllers, decorators, and DTOs — but pulling in a full Nest runtime (modules, a DI container, its own HTTP adapter) inside a Next.js app is a lot of machinery for what is usually just "organize my API routes."

nextjs-nestapi is the middle ground.

What it looks like​

import {Controller, Get, Post, Body, type RouteContext} from "nextjs-nestapi";
import {CreateHelloDto} from "./dto";

@Controller("/hello")
export class HelloController {
  @Get("/:id")
  getOne(context: RouteContext) {
    return {id: context.params.id};
  }

  @Post("")
  create(@Body(CreateHelloDto) dto: CreateHelloDto) {
    return {created: dto};
  }
}

One catch-all app/api/[[...route]]/route.ts dispatches every request to your registered controllers. @Body(DtoClass) validates the request against a class-validator DTO and returns a structured error response automatically when it fails. No DI container, no modules — just plain classes wired together with createApplication().

Why not just use NestJS's own Next.js adapter, or plain route handlers?​

• Plain route handlers work fine for a few endpoints, but you end up hand-rolling the same body-parsing, validation, and error-shaping logic in every file.
• A full NestJS app running inside Next.js gives you all of that back, plus a DI container, modules, guards, pipes, and interceptors you may not need — and a second framework's request lifecycle running alongside Next.js's own.

nextjs-nestapi picks a narrower scope on purpose: routing, DTO validation, and middleware, implemented directly on top of NextRequest/NextResponse. See Limitations for the full list of what's deliberately left out.

Get started​

npx nextjs-nestapi new my-app

or wire it into an existing project:

npm install nextjs-nestapi class-validator class-transformer
npx nextjs-nestapi init

Head to the Quick start to build your first controller.