Manual install
Create Next.js project with App Router and TypeScript
Follow this instruction to install Next.js. Use TypeScript, App Router and src/ directory.
npx create-next-app my-app --ts --appcd my-appInstall “vovk” and “vovk-client”
npm i vovk vovk-clientCreate an empty config file
Create vovk.config.ts at the root of the project with the following content:
// @ts-check
/** @type {import('vovk-cli').VovkConfig} */
const vovkConfig = {};
export default vovkConfig;Install validation library and enable client validation
Install one of the validation libraries with some additional packages.
Update “dev” NPM script
There are two ways to run Vovk.ts and Next.js server concurrently: explicitly and implicitly. The explicit way is to install concurrently package and run both scripts with it, this requires PORT variable to be set. The implicit way is to make Vovk.ts to run Next.js server by itself. At this case vovk-cli will assign the port automatically.
Explicit
Install concurrently:
npm i -D concurrentlyUpdate the “dev” script in package.json:
"scripts": {
"dev": "PORT=3000 concurrently 'vovk dev' 'next dev' --kill-others"
}Enable decorators
In your tsconfig.json set "experimentalDecorators" to true.
{
"compilerOptions": {
"experimentalDecorators": true
// ...
}
}Create controller
Create HelloController.ts at /src/modules/hello/ with same-named static class.
import { get, prefix } from 'vovk';
@prefix('greetings') // prefix is optional
export default class HelloController {
@get('greeting')
static getHello() {
return { greeting: 'Hello, World!' };
}
}Create root segment
Create /src/app/api/[[…vovk]]/route.ts where [[…vovk]] is a folder name indicating what Next.js documentation calls “Optional Catch-all Segment” that can be customized. This is the root entry point for API routes.
At the code below HelloRPC indicates the name of the exported client library and HelloController is the controller class created above.
import { initSegment } from 'vovk';
import HelloController from '../modules/hello/HelloController';
export const runtime = 'edge'; // this setting is optional
const controllers = { HelloRPC: HelloController };
// export types used by the client
export type Controllers = typeof controllers;
export const { GET, POST, PUT, DELETE } = initSegment({ controllers });Run “vovk dev”
Run npm run dev to start Vovk.ts and Next.js concurrently.
npm run devNavigate to http://localhost:3000/api/greetings/greeting to see the result.
Create a React component
Now the client is generated you can safely import your client library from vovk-client.
'use client';
import { useState } from 'react';
import { HelloRPC } from 'vovk-client';
import type { VovkReturnType } from 'vovk';
export default function MyComponent() {
const [serverResponse, setServerResponse] = useState<VovkReturnType<typeof HelloController.getHello>>();
return (
<>
<button
onClick={async () => {
const response = await HelloController.getHello();
setServerResponse(response);
}}
>
Get Greeting from Server
</button>
<div>{serverResponse?.greeting}</div>
</>
);
}Open http://localhost:3000 and see the result.
Note that if you’re using VSCode you’re probably going to need to restart TS server each time when you add a new controller class to your app.
Next.js Server Components are also supported but require to define absolute URL (by default all requests are made to /api). Check the Server Component Example for more information.
Deploy
In order to build the client (not the schema) at node_modules you need to run the following command after dependency installation and before building the app.
npx vovk generate