RESTful RPC for Next.js

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

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,
    });
  }
}

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 });

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

Manual Install

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