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.
docsRoute
✓ import { docsRoute } from 'next-rest-framework'
✗ const { docsRoute } = require('next-rest-framework')
Used for App Router documentation endpoints. For Pages Router, use `docsApiRoute`.
routeHandler
✓ import { routeHandler } from 'next-rest-framework'
✗ import routeHandler from 'next-rest-framework'
Primary function for defining App Router API routes. For Pages Router, use `apiRoute`.
TypedNextResponse
✓ import { TypedNextResponse } from 'next-rest-framework'
✗ import { NextResponse } from 'next/server'
Use `TypedNextResponse` for type-safe responses that integrate with NRF's schema validation and OpenAPI generation.
createRestApiHandler
✓ import { createRestApiHandler } from 'next-rest-framework'
✗ import { createRestHandler } from 'next-rest-framework'
This is the Pages Router equivalent for REST APIs. Be careful not to confuse with `createRestHandler` for the App Router.
This quickstart demonstrates how to set up a self-documenting REST API with GET and POST methods using Next.js App Router and Next REST Framework, including a Zod schema for validation and a docs endpoint for auto-generated OpenAPI documentation. It also shows the CLI command for spec generation.
import { docsRoute, routeHandler, routeOperation, TypedNextResponse } from 'next-rest-framework';
import { z } from 'zod';
// 1. Define your data schema using Zod
const todoSchema = z.object({
id: z.number().int().positive(),
title: z.string().min(1),
completed: z.boolean(),
});
type Todo = z.infer<typeof todoSchema>;
// In-memory data store for demonstration
const todos: Todo[] = [
{ id: 1, title: 'Learn Next.js', completed: false },
{ id: 2, title: 'Build an API with NRF', completed: true },
{ id: 3, title: 'Deploy to Vercel', completed: false },
];
// 2. Create your API docs endpoint (App Router: src/app/api/docs/route.ts)
// Visit /api/docs to see the auto-generated documentation
export const GET_DOCS = docsRoute({
openApiObject: {
info: {
title: 'My Todo API',
version: '1.0.0',
description: 'Automatically generated API documentation for the Todo List.',
},
servers: [{ url: 'http://localhost:3000/api' }],
},
// The CLI will use this path to generate the openapi.json file
// By default, it generates to public/openapi.json if not specified here
});
// 3. Create your REST API route (App Router: src/app/api/todos/route.ts)
export const { GET, POST } = routeHandler({
GET: routeOperation({
operationId: 'getTodos',
tags: ['Todos'],
summary: 'Retrieve all todos',
description: 'Fetches a list of all available todo items.',
})
.output({
status: 200,
contentType: 'application/json',
schema: z.array(todoSchema),
})
.handler(async () => {
// Simulate network delay
await new Promise(resolve => setTimeout(resolve, 50));
return TypedNextResponse.json(todos, { status: 200 });
}),
POST: routeOperation({
operationId: 'createTodo',
tags: ['Todos'],
summary: 'Create a new todo',
description: 'Adds a new todo item to the list.',
})
.input({
contentType: 'application/json',
body: todoSchema.omit({ id: true }), // ID is auto-generated
})
.output({
status: 201,
contentType: 'application/json',
schema: todoSchema,
})
.handler(async (req) => {
const newTodo: Todo = {
id: todos.length > 0 ? Math.max(...todos.map(t => t.id)) + 1 : 1,
...req.body,
};
todos.push(newTodo);
return TypedNextResponse.json(newTodo, { status: 201 });
}),
});
// To generate the OpenAPI specification file (public/openapi.json by default),
// add a script to your package.json:
// {
// "scripts": {
// "generate-api-spec": "npx next-rest-framework generate"
// }
// }
// Then run: npm run generate-api-spec
// After running, visit /api/docs in your browser to see the interactive documentation.
Errors
Common errors & fixes
ReferenceError: TypedNextResponse is not defined
`TypedNextResponse` was not imported or is misspelled.
fixEnsure `TypedNextResponse` is imported from `next-rest-framework`: `import { TypedNextResponse } from 'next-rest-framework';` Error: Invalid OpenAPI object configuration. Check your docsRoute options.
The `openApiObject` provided to `docsRoute` (or `docsApiRoute`) is malformed or missing required fields like `info.title` or `info.version`.
fixReview the `openApiObject` configuration within your `docsRoute` handler and ensure it adheres to the OpenAPI Specification (OAS) structure, particularly the `info` object.
TypeError: Cannot read properties of undefined (reading 'body') in handler
Attempting to access `req.body` in a route operation that doesn't explicitly define an `input` schema with a `body` property, or where the `contentType` doesn't match the incoming request.
fixEnsure your `routeOperation` includes an `input` configuration with a `body` schema and the correct `contentType` matching what your API expects. Example: `.input({ contentType: 'application/json', body: yourZodSchema })`. Error: `npx next-rest-framework generate` failed. Could not parse route files.
The CLI tool might be struggling to parse your TypeScript files, possibly due to missing `tsx` or incorrect project setup for the CLI.
fixEnsure `tsx` is installed (`npm install --save-dev tsx`) and that your `generate` script correctly points to your `docsRoute` configuration if you have multiple or non-standard paths. For example: `npx next-rest-framework generate --config src/app/api/docs/route.ts`.
Audit
Dependencies
nextrequiredCore dependency as a Next.js framework, requires Next.js >= v12.
zodrequiredRequired for input/output schema validation and OpenAPI schema generation, requires Zod >= v3.
zod-form-dataoptionalNeeded for handling form data schemas, requires zod-form-data >= v2.
tsxoptionalOptional dependency for the CLI when working with TypeScript.