RESTful RPC for Next.js

Transforms Next.js App Router into a powerful REST API platform with RPC integration

1
Create
Create a static class and define API endpoints with decorators
// /src/modules/post/PostController.ts
import { get, prefix, type VovkRequest } from 'vovk';
import PostService from './PostService';
 
@prefix('posts')
export default class PostController {
  /**
   * Create a comment on a post
   * POST /api/posts/:postId/comments
   */
  @post(':postId/comments')
  static async createComment(
    // decorate NextRequest type with body and query types
    req: VovkRequest<
      { content: string; userId: string }, 
      { notificationType: 'push' | 'email' }
    >,
    { postId }: { postId: string } // params
  ) {
    // use standard Next.js API to get body and query
    const { content, userId } = await req.json();
    const notificationType = req.nextUrl.searchParams
      .get('notificationType');
 
    // perform the request to the database in a custom service
    return PostService.createComment({ 
      postId, content, userId, notificationType,
    });
  }
}
2
Init
Initialise the controller at Next.js Optional Catch-all Segment
// /src/app/api/[[...vovk]]/route.ts
import { initVovk } from 'vovk';
import PostController from '../../../modules/post/PostController';
 
export const runtime = 'edge'; // optional
 
// list of all controllers
const controllers = { PostController };
 
// used to map types for the generated client library
export type Controllers = typeof controllers;
 
export const { GET, POST } = initVovk({ controllers });
3
Use
Import the auto-generated fetching library from "vovk-client"
'use client';
import { useState } from 'react';
import { PostController } from 'vovk-client';
import type { VovkReturnType } from 'vovk';
 
export default function Example() {
  const [response, setResponse] = useState<VovkReturnType<typeof PostController.createComment>>();
 
  return (
    <>
      <button
        onClick={async () => setResponse(
          await PostController.createComment({
            body: { 
              content: 'Hello, World!', 
              userId: '1', 
            },
            params: { postId: '69' },
            query: { notificationType: 'push' }
          })
        )}
      >
        Post a comment
      </button>
      <div>{JSON.stringify(response)}</div>
    </>
  );
}

Quick Install

npx create-next-app -e https://github.com/finom/vovk-hello-world

Features

Good old REST with RPC

World first REST API library with RPC support. You can call your API methods directly from the client-side.

Easy to Learn

Specially designed for Next.js App Router, Vovk doesn't introduce complex abstractions by being just a wrapper over route handlers making it easy to learn.

Edge Runtime

Edge runtime is available out of the box. Your REST API is geographically closer to users.

Code Splitting

Apps built with Vovk.ts utilise service-controller pattern that inspired by the beauty of NestJS.

Text streaming for LLMs

Create AI apps powered by the modern TypeScript syntax with disposable objects and async generators.

Web Workers at your Fingertips

Leverage the new concept of "Worker Procedure Call" to execute resource-intensive code on a separate browser thread using elegant syntax.

Enjoy Mapped Types

You can jump straight from the client-side to the controller implementation, making the development process easier, thanks to Mapped Types in TypeScript.

Bonus Features

Highly Customizable
import { UserController } from 'vovk-client';
 
// ...
 
UserController.createUser({ 
    body,
    query,
    params,
    successToast: 'Successfully created a new user',
    useAuth: true,
    sentryLogErrors: true,
});

You can completely redefine the behavior of the generated library by implementing your own fetching function. This allows tight integration with your application's state logic or the addition of extra options.

Read Docs
Back-end for React Native
import { GreetingController } from 'vovk-client';
 
// ...
<Pressable 
    onPress={async () => {
        setGreetingResponse(
            await GreetingController.getGreeting()
        );
    }}
>
    <Text>Get Greeting</Text>
</Pressable>

Creating a full-stack React-Native application has never been so easy! Set up a project with React Native, Next.js, and Vovk.ts, and start making requests.

See example
Easy to Distribute
import { MyController } from 'my-client-library';
 
// ...
 
using stream = await MyController.streamTokens();
 
for await (const token of stream) {
    console.log(token);
}

Bundle and distribute your REST API client library with ease. Examples at this documentation utilize the vovk-examples package, bundled with Webpack, which accesses REST endpoints from the Examples Website API.

See Examples Repository

Sponsors

Sponsor the author of this project on Github ♥️
You can also contact me via email from my Github profile