Quick Start
Create a Next.js app (App Router + TypeScript)
npx create-next-app@latest my-app --ts --app --src-dircd my-appInitialize 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 initMore info:
Create a segment
Create the root segment at ./src/app/api/[[…vovk]]/route.ts:
npm exec -- vovk new segmentMore 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:
npm exec -- vovk new controller service userimport { 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 devThen 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:
'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:
npm exec -- vovk generateMore info: