@ddadaal/next-typed-api-routes NPM

next-typed-api-routes

npm

Write a Schema interface in your API route file, and you get

route parameters validation and type completion
typed API clients
faster JSON response serialization

all at one command!

Requirement for the target Next.js Project

Use TypeScript
Set "baseUrl": "." in tsconfig.json compilerOptions part

{
  "compilerOptions": {
    "baseUrl": "."
  }
}

All codes should live in src dir next.js src directory

Get Started

Install the package in your Next.js TypeScript project

npm install --save @ddadaal/next-typed-api-routes

Create a API route src/pages/api/test.ts with the following content

import { route } from "@ddadaal/next-typed-api-routes";

interface Value {
  articleId: number;
}

export interface TestApiSchema {
  method: "POST";

  query: {
    a?: string | number;
  };

  body: {
    test: string;
  };

  responses: {
    200: { test: string; }
    403: { message: string; }
  }
}

export default route<TestApiSchema>("TestApiSchema", async (req) => {
  const { a } = req.query;
  const { test } = req.body;

  return { 200: { test: test + "" + a } };
});

Run npx ntar schema && npx ntar client

schemas.json will be generated at the module folder under node_modules. You should never edit it directly. The project cannot start without this file.

src/apis/api.ts will be generated at src/apis.

Import the api variable from src/apis/api.ts to use the client.

import { api } from "src/apis/api";

api.testApi({ query: {}, body: { test: "123" } })
  .httpError(403, ({ message }) => { console.log(403, message); })
  .then(({ test }) => { console.log(test); });

Important Add ntar schema to postinstall script in your package.json

so that schemas.json will be generated every time your project is npm installed.

{
  "scripts": {
    "postinstall": "ntar schema"
  }
}

Updating existing API Routes

To convert a normal API Routes to a type checked one, all you need to do is

Write a valid Schema interface
Wrap the handler function with route function, specify the name of Schema interface as the type argument and first argument

The Get Started part provides an example of a correctly formatted API route file. ntar will report errors if Incorrect route file is found.

Run ntar schema when the Schema interface is changed.

Run ntar client when the HTTP method or URL or the name of schema is changed.

Schema Interface Specification

The shape of Schema interface is defined as follows:

// The name of the schema must be unique across the whole project
interface TestSchema {
  // Required. Must be a valid CAPITALIZED string literal type of HTTP method (GET, POST, PATCH)
  method: "POST";

  // Optional. Define the path param and query (to align with next.js)
  query: {
    // Supports most type constructs
    property?: string | number | AnotherInterface | Pick<{ number: string }, "number">;
    
    /**
     * You can also use jsdoc for more specific limits
     * You can use keywords and values from JSON Schema Draft-07
     * @format email
     * @maxLength 50
     */
    anotherProperty: string;
  }

  // Optional. Define the body
  body: {
    // Supports most type constructs
    property?: string | number | AnotherInterface | Pick<{ number: string }, "number">;
  } 

  // Required. Define the responses
  responses: {
    // Key as response code. 
    // Only one [200, 300) response should exist. It will be considered by clients as the success response
    // If the success response has no payload, the status code must be 204.
    200: {
      // Supports most type constructs
      property?: string | number | AnotherInterface | Pick<{ number: string }, "number">;
    };

    // If the code has no payload, set the type to null
    404: null;
  }
}

Tips

All schemas and used models must have globally unique name
Return a { [statusCode]: payload } object in a route to take advantages of response body type check and faster JSON serialization
To ensure that client bundle doesn't include unnecessary packages (e.g. ajv, fast-json-stringify, which are only used in server side),
- import packages only from @ddadaal/next-typed-api-routes/lib/client in client files,
- import types with import type clause

Thanks

Ajv for JSON Schema validation
vega/ts-json-schema-generator for generating json schema from typescript
fast-json-stringify for faster JSON response serialization
fastify for inspiration or unified validation and serialization using JSON schema