Skip to Content
Quick Start

Quick Start

Create a Next.js app (App Router + TypeScript)

npx create-next-app@latest my-app --ts --app --src-dir
cd my-app

Initialize Vovk.ts

You will be prompted to answer a few questions. The CLI will install the selected dependencies, update npm scripts, enable experimentalDecorators in tsconfig.json, and create a config file.

npx vovk-cli@latest init

More info:

Create a segment

Run the following to create the root segment at ./src/app/api/[[…vovk]]/route.ts:

npx vovk new segment

More info:

Generate a controller and a service

This command scaffolds UserController.ts and UserService.ts from built-in (customizable) templates under ./src/modules/user/ and updates the segment’s route.ts:

npx vovk new controller service user
src/modules/user/UserController.ts
import { procedure, prefix, get, put, post, del, operation } from 'vovk';
import { z } from 'zod';
import UserService from './UserService';
 
@prefix('users')
export default class UserController {
  // ...
  @operation({
    summary: 'Get single user',
  })
  @get('{id}')
  static getSingleUser = procedure({
    params: z.object({
      id: z.string(),
    }),
    handle(_req, { id }) {
      return UserService.getSingleUser(id);
    },
  });
  // ...
}

More info:

Start the server and inspect an endpoint

The dev script runs the Next.js dev server and the Vovk.ts watcher in parallel. While running, Vovk.ts generates schema files in .vovk-schema/ (commit these) and the client library in node_modules/.vovk-client.

npm run dev

Then open: http://localhost:3000/api/users/123 
You’ll see a placeholder response from UserController.getSingleUser: {"message":"TODO: get single user","id":"123"}

You can also check the schema endpoint (available only when NODE_ENV is set to development) at http://localhost:3000/api/_schema_ 

More info:

Create a React component to display data

Import the generated client library and call the RPC method:

src/app/page.tsx
'use client';
import { useEffect, useState } from 'react';
import type { VovkReturnType } from 'vovk';
import { UserRPC } from 'vovk-client';
 
export default function Home() {
  const [resp, setResp] = useState<VovkReturnType<typeof UserRPC.getSingleUser> | null>(null);
 
  useEffect(() => {
    void UserRPC.getSingleUser({ params: { id: '123' } }).then(setResp);
  }, []);
  return <pre>Response: {JSON.stringify(resp, null, 2)}</pre>;
}

You can alternatively use React Query  for request state management:

import { useQuery } from '@tanstack/react-query';
import { UserRPC } from 'vovk-client';
// ...
const { data, error, isLoading } = useQuery({
  queryKey: UserRPC.getSingleUser.queryKey(),
  queryFn: () => UserRPC.getSingleUser({ params: { id: '123' } }),
});

More info:

Deploy

The vovk init command adds a prebuild script so vovk generate runs automatically before next build. If you adjust scripts manually, run:

npx vovk generate

More info:

Last updated on
About Vovk.tsManual Install