Core Concepts

Next-TS-API is built around several core concepts that work together to provide end-to-end type safety for your Next.js API routes.

Type Generation

Next-TS-API automatically generates TypeScript types for your API routes by analyzing your route handlers. This includes:

Request body types
Response payload types
Query parameters
Path parameters

The generated types are stored in types/next-ts-api.ts and are automatically updated when you make changes to your API routes.

Route Handlers

Route handlers in Next-TS-API are enhanced versions of Next.js route handlers with built-in type safety:


import { NextApiRequest } from 'next-ts-api';
 
// POST handler with typed request body
export async function POST(
  request: NextApiRequest<{
    title: string;
    completed: boolean;
  }>
) {
  const { title, completed } = await request.json();
  return Response.json({ success: true, data: { title, completed } });
}

Type-Safe API Client

The API client provides type-safe access to your API routes:


import { createNextFetchApi } from "next-ts-api";
import { type ApiRoutes } from "../types/next-ts-api";
 
// Create a type-safe API client
export const api = createNextFetchApi<ApiRoutes>();
 
// All API calls are now type-safe
const response = await api('users', {
  method: 'POST',
  body: {
    name: 'John',  // Type checked!
    email: 'john@example.com'  // Type checked!
  }
});

Best Practices

Always Import from next-ts-api:


import { NextApiRequest } from 'next-ts-api';
// NOT from 'next/types'

Use Type Annotations:


// Good - explicit types
export async function POST(
  request: NextApiRequest<CreateTodoInput>
) { }
 
// Avoid - implicit any
export async function POST(request) { }

Leverage Generated Types:


import { type ApiRoutes } from "../types/next-ts-api";
// Use throughout your application

Next Steps

Check out the API Reference for detailed documentation
See Examples for common usage patterns
Learn about Contributing to Next-TS-API