💡 Using Next.js as a platform for a well-structured REST API

[finom]

As you know, Next.js is positioned as a React framework, but its back-end capabilities are limited by the design of the route.ts file. There are multiple solutions to this problem, such as tRPC or GraphQL, but I didn't find them satisfactory. My goal was to create a REST API with the structured approach introduced in NestJS, while using Next.js as the core framework. I don't consider these technologies bad; in fact, they are amazing tools used by millions of developers. It's purely a matter of preference. Perhaps I'm too conservative, but consider that the first website I built was based on the <frameset> HTML tag long-long time ago.

Over the last year, I've been working on a solution that allows Next.js to be used as a full-stack framework. I attempted to merge Next.js and NestJS into a unified system using Next.js middleware, but as you know it's too limited and don't allow to do many of the things that come to your mind. After much hard work and continuous thought, I am proud to present the final iteration of my solution to this challenge: Vovk.ts - REST for Next. This is an add-on over the public Next.js App Router API that leverages the so-called Optional Catch-all Segment to initialize decorated controller classes inspired by NestJS.

This library includes a CLI that generates a client library in node_modules with same-named variable names, which can be imported from any platform supporting the standard fetch function. This encompasses client components, server components, React Native apps, and other JavaScript environments. To create a new controller, you need to follow three steps.

1. Create the controller static class (you may also want to create a service).

// /src/modules/hello/HelloController.ts
import { get, prefix } from 'vovk';

@prefix('hello') // prefix is optional
export default class HelloController {
  /**
   * GET /api/hello/greeting
   */
  @get('greeting')
  static getHello() {
    return { greeting: 'Hello world!' };
  }
}

2. Add the controller to the list of controllers at Optional Catch-all Segment.

// /src/app/api/[[...vovk]]/route.ts
import { initVovk } from 'vovk';
import HelloController from '../../../modules/hello/HelloController';

// optionally enable edge runtime to serve the API geographically closer to your users
export const runtime = 'edge';

// list of all controllers
const controllers = { HelloController };

// used to map types for the generated client library
export type Controllers = typeof controllers;

export const { GET, POST } = initVovk({ controllers });

3. Use the controller in your component with auto-inferred types.

'use client';
import { useState } from 'react';
import { HelloController } from 'vovk-client';
import type { VovkClientReturnType } from 'vovk';

export default function Example() {
  const [response, setResponse] = useState<VovkClientReturnType<typeof HelloController.getHello>>();

  return (
    <>
      <button
        onClick={async () => setResponse(
          await HelloController.getHello()
        )}
      >
        Get Greeting from the Server
      </button>
      <div>{response?.greeting}</div>
    </>
  );
}

After that, you simply add more decorated static methods to extend the controller with additional features. As you might expect, the endpoints can be called using the standard fetch method, like so:

const resp = fetch('/api/hello/greeting', { method: 'GET' });

It's also worth mentioning that the compiled library can be easily bundled with Webpack and distributed through NPM, CDN, or any other suitable method, since it acts as a minimal function that calls fetch.

---

The main difference from other libraries is that Vovk.ts is specifically designed for the Next.js App Router. It avoids introducing complex abstractions and does not modify the request object, acting merely as a wrapper over Next.js route handlers. If you're familiar with using them, you already know how to handle operations like retrieving the JSON body, Request Body FormData, search query, making a redirect, using cookies, accessing headers, etc.

import { redirect } from 'next/navigation';
import type { NextRequest } from 'next/server';
// ...
export default class HelloController {
  /**
   * POST /api/hello/greeting?id=...
   */
  @post('greeting')
  static async postHello(req: NextRequest) {
    const body = await req.json(); // type: any
    const id = req.nextUrl.searchParams.get('id'); // type: string | null
    // ...
    redirect('/api/another/endpoint')
    // ...
  }
}

In order to make the client recognise types properly, you should use VovkRequest that modifies return types for req.json and req.nextUrl.searchParams.get. This also illiminates a need to use as to convert the return type.

// ...
static async postHello(req: VovkRequest<Greting, { id: string }>) { // 
    const body = await req.json(); // type: Greting
    const id = req.nextUrl.searchParams.get('id'); // type: string
// ...

At the example above query id uses string type but it also may be typed with a flavoured type.

---

Vovk.ts comes with a bunch of examples covering the most common use-cases, which you can find here. Besides basic examples, you may also find it interesting to see how to implement a text streaming endpoint and a real use-case of OpenAI chat. Instead of using workarounds provided by the AI SDK, you can delegate the async iterable using the yield* syntax:

// ... OpenAiController.createChatCompletion
yield* await openai.chat.completions.create({
  messages,
  model: 'gpt-3.5-turbo',
  stream: true,
});
// ...

and on the front-end you can use use disposable async iterable to iterate over the delegated items:

// ...
// this syntax closes the stream when code block has ended or interupded because of an error
using completion = await OpenAiController.createChatCompletion({
  body: { messages },
});

// async disposables are also supported:
// await using completion = ...

for await (const chunk of completion) {
  console.log(chunk);
}

In other words, you can use any third-party AI library on server-side that uses generators to transcribe them into a client-side code.

The last but not least thing is that the generated library is fully customizable. You can override its behavior by adding custom flags, auth, make it return custom data, or tightly integrate with your application state. This part is explained in the documentation.

import { UserController } from 'vovk-client';

// ...

UserController.createUser({ 
    body,
    query,
    successToast: 'Successfully created a new user',
    useAuth: true,
    sentryLogErrors: true,
});

Vovk.ts comes with other cool features:

• Error objects on server-side are re-thrown on the client-side;
• Requests can be validated with Zod or with your own code;
• Endpoints can be automatically generated from the method names;
• Static endpoints can be created in a few lines of code;
• There is also a friendly Web Worker interface;
• The documentation includes a way to structure a large application.

But that's a different story. In this brief post, I wanted to highlight the core capabilities provided by the library.

Thank you for reading. If you have any questions, I would be happy to answer them.

Vovk.ts on Github