Skip to Content
Quick Start

Quick Start

With an agent

npx skills add finom/vovk

Then ask your agent, for example: “Add an API to this app for a todo list.” The prompt doesn’t have to name Vovk.ts. Agent Skills has more prompts, the per-agent install and the Claude Code plugin.

Without an agent

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

The CLI asks a few questions. Then it installs the dependencies you chose, updates the npm scripts, enables experimentalDecorators in tsconfig.json and creates a config file.

npx vovk-cli@latest init

More info:

Create a segment

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 writes user-controller.ts and user-service.ts to ./src/modules/user/ from built-in templates, which you can customize, and updates the segment’s route.ts:

npx vovk new controller service user
src/modules/user/user-controller.ts
import { procedure, prefix, get, put, post, del, operation } from 'vovk';
import { z } from 'zod';
import UserService from './user-service';
 
@prefix('users')
export default class UserController {
  // ...
  @operation({
    summary: 'Get single user',
  })
  @get('{id}')
  static getSingleUser = procedure({
    params: z.object({
      id: z.string(),
    }),
  }).handle(async (_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 together. Meanwhile, Vovk.ts writes the schema files to .vovk-schema/ (commit them) and the client library to src/client (git-ignored, generated again on every build).

npm run dev

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

The segment also serves its schema at http://localhost:3000/api/_schema_ , only when NODE_ENV is development.

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 '@/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>;
}

Or manage the request state with React Query :

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

More info:

Deploy

vovk init adds a prebuild script, so vovk generate runs before next build. Yarn 2+ doesn’t run pre scripts, so there vovk init puts vovk generate at the start of build. If you change the scripts yourself, run it before the build:

npx vovk generate

More info:

Last updated on
About Vovk.tsAgent-Ready App