API Reference

This page provides detailed documentation for Next-TS-API’s core APIs and types.

Core Types

NextApiRequest


type NextApiRequest<Body, Query = Record<string, string>> = {
    json: () => Promise<Body>;
    formData: () => Promise<TypedFormData<Body>>;
    nextUrl: {
        searchParams: URLSearchParamsType<Query>;
    }
}

The NextApiRequest type extends the standard Next.js Request type with type-safe body parsing. The Body type parameter is shared by both json() (for JSON payloads) and formData() (for multipart uploads), and Query provides typed access to searchParams.

ApiRoutes


type ApiRoutes = {
  [path: string]: {
    [method in HttpMethod]?: {
      body?: unknown;
      form?: unknown;
      response: unknown;
      params?: Record<string, string>;
      query?: Record<string, string>;
    };
  };
};

Generated type that describes your API routes structure. body and form describe the JSON and multipart payloads respectively.

HttpMethod


type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

Supported HTTP methods.

Type Extractors

These helpers power the generated types/next-ts-api.ts file. You rarely use them directly, but they explain how each part of a route is inferred:


type ExtractNextBody<T>     // JSON body type from a handler
type ExtractNextForm<T>     // multipart form data type from a handler
type ExtractNextQuery<T>    // searchParams type from a handler
type ExtractNextParams<T>   // path params type from a handler
type ExtractNextResponse<T> // response type (error responses excluded)

API Client

createNextFetchApi


function createNextFetchApi<T extends ApiRoutes>(config?: {
  baseUrl?: string;
}): ApiClient<T>;

Creates a type-safe API client for your routes.

ApiClient


type ApiClient<T extends ApiRoutes> = <
  TPath extends keyof T,
  TMethod extends keyof T[TPath]
>(
  path: TPath,
  options: {
    method: TMethod;
    body?: T[TPath][TMethod]['body'];
    form?: T[TPath][TMethod]['form'];
    params?: T[TPath][TMethod]['params'];
    query?: T[TPath][TMethod]['query'];
    headers?: HeadersInit;
  }
) => Promise<TypedResponse<T[TPath][TMethod]['response']>>;

The type-safe API client function type. It resolves to a standard Response whose json() method is typed to the route’s response — so you always call await response.json() to read the typed payload.

Pass body for JSON requests or form for multipart uploads (the client builds the FormData for you). params fill [id]-style path segments and query becomes the URL search string.

Configuration

nextTsApi


import { nextTsApi } from 'next-ts-api/config';
 
function nextTsApi(options?: {
  dir?: string;
  outDir?: string;
  outFile?: string;
}): Plugin;

Next.js plugin for type generation.

Parameters:

options.dir: The directory to scan for API routes
options.outDir: The directory to output the generated types
options.outFile: The file to output the generated types

Example:


// next.config.js
const { nextTsApi } = require('next-ts-api/config');
const withNextTsApi = nextTsApi({
  outDir: 'src/types',
});
 
const nextConfig = {
  // ... your other config
};
 
export default withNextTsApi(nextConfig);

Custom error class for API errors.

Next Steps

See Examples for practical usage
Learn about Core Concepts
Check out Contributing guidelines