# Finom Vovk Init

> Vovk.ts initialization

- Skill: `tomevault-io/finom-vovk-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/finom-vovk-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/finom-vovk-init/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/finom-vovk-init

---


# Vovk.ts initialization

Vovk.ts is TypeScript-first RPC/API framework plugging into Next.js App Router. Ships CLI (`vovk-cli`) that installs deps, toggles `experimentalDecorators` in tsconfig, wires up npm scripts, writes `vovk.config.mjs`. Coordinated edits easy to get wrong by hand, so this skill is thin wrapper: preps env, delegates to CLI, handles follow-ups.

Plugin is source of truth for everything Vovk-related — **don't `WebFetch` vovk.dev** while running this skill. If step here looks incomplete, that's skill bug, surface it.

## Interactive prompts

`vovk-cli` and `create-next-app` both interactive. When prompt appears skill doesn't cover, accept default (usually "yes" or CLI's recommended choice) unless user told you otherwise. Don't predict every prompt up front — defaults change, user can override afterward.

## Decide the path

Inspect current working dir:

- `package.json` exists with `next` in `dependencies` or `devDependencies` → **Path A (existing Next.js project)**.
- Otherwise → **Path B (new project)**.

If `package.json` exists but no `next`, it's existing non-Next.js project. Ask whether to add Next.js into current dir or scaffold new one in subdir — don't silently pollute their repo.

## Path A — existing Next.js project

### 1. Verify prerequisites (bundled)

Check all three in parallel:

- **Node version**: `node --version` — require ≥ 22.
- **Next.js version**: `package.json` `next` must resolve to ≥ 15.0.0.
- **App Router directory**: `src/app/` or `app/` must exist (even if empty) — Vovk mounts route handler there. If only `pages/` exists, trivial fix: create empty `app/` (or `src/app/`, matching project's convention) alongside. App Router and Pages Router coexist fine — no migration needed just to use Vovk.

If any check fails, **bundle all failures into one message** and ask user how to proceed. Don't drip-feed one at a time. Example:

> "Two blockers before Vovk can run:
> 1. Node is on v20.18.0 — Vovk needs ≥ 22. You'll need to upgrade it yourself (`nvm install 22 && nvm use 22` or equivalent); I won't touch your Node install.
> 2. Next.js is on `^14.2.5` — I can run `npx @next/codemod@canary upgrade latest` to move to 15. It can introduce breaking changes, so reviewing the diff afterward is a good idea.
>
> Also: no `app/` directory yet — I'll create an empty `src/app/` alongside `pages/` so Vovk has somewhere to mount. That coexists with your existing Pages Router fine.
>
> Want me to proceed after you bump Node?"

Suggested fixes per failure:

- **Node < 22**: surface, don't auto-run. OS-level concern.
- **Next.js < 15**: `npx @next/codemod@canary upgrade latest`.
- **No App Router directory**: create empty `src/app/` (if project uses `src/`) or `app/` (otherwise). One-line `mkdir` — don't run heavyweight `app-dir-migration` codemod just to add Vovk. Migrating existing Pages Router code to App Router is user's call, not Vovk prereq.

Proceed only on explicit user confirmation for non-trivial fixes (Node, Next upgrade). Empty-directory creation rides that same confirmation.

### 2. Detect the validation library

Before running `vovk init`, decide which validation library to pick at CLI's interactive prompt. Vovk supports three (all Standard Schema–compliant): **Zod**, **Valibot**, **ArkType**. Priority:

1. **Explicit user preference** — if user already said "use Valibot" (or Zod, ArkType), that wins. Skip rest.
2. **Installed in project** — inspect `package.json` `dependencies` + `devDependencies`. If exactly one of `zod` / `valibot` / `arktype` present, use it. Reusing what's in repo keeps dep footprint flat, avoids forcing second validation stack onto codebase that already has one.
3. **Fallback** — none installed? Use **Zod**. Framework default and pairs with `vovk-ajv` for client-side validation w/o extra prompts.

If two or three installed at once, don't guess — ask:

> "Your `package.json` has both `zod` and `valibot`. Which should Vovk use for procedure validation? (They can coexist — this just picks the one the CLI wires into codegen.)"

Remember decision; step 3 feeds it into prompt.

### 3. Run `vovk init`

**Heads-up for pnpm projects.** CLI scaffolds `vovk-client` dep by default, which step 5 swaps for source-tree `@/client` import. Tell user up front: *"On pnpm, init is two-pass — CLI installs `vovk-client`, then I'll move composed client into `src/client/` and remove the package, since pnpm's strict layout breaks the default re-export. End state is one path: `import … from '@/client'`."* Intentional and documented; mention before running CLI so user doesn't read step 5 as cleanup-after-mistake.

From project root:

```bash
npx vovk-cli@latest init
```

CLI auto-detects package manager from lockfiles and handles its own prompts. When it asks for validation library, answer with choice from step 2. Accept CLI's recommended defaults for any other prompt (decorators, bundle, updateScripts, lang) per interactive-prompts rule above — unless user said otherwise.

If CLI errors out, report error verbatim and stop. Don't patch half-init state by hand.

### 4. Verify the result

After init finishes, confirm:

- `vovk.config.mjs` exists at project root, with `outputConfig.imports.validateOnClient` and `moduleTemplates.controller` / `moduleTemplates.service` set.
- `tsconfig.json` has `"experimentalDecorators": true` under `compilerOptions`.
- `package.json` `dependencies` gained `vovk` + `vovk-client` + `vovk-ajv` (always) + chosen server-side validation library. For `zod`: `zod`. For `valibot`: `valibot` + `@valibot/to-json-schema`. For `arktype`: `arktype`. `vovk-ajv` is the client-side validator regardless of server-side choice.
- `package.json` `devDependencies` gained `vovk-cli`.
- `package.json` `scripts` — existing `dev` is **replaced** with `vovk dev --next-dev` (vovk's dev wrapper around `next dev`), and new `prebuild` script added running `vovk generate` (so RPC codegen runs before every `next build`). `build` and `start` left untouched.

If user originally had custom `dev` script, flag replacement explicitly — user may want to preserve custom flags. CLI's `--update-scripts explicit` mode keeps scripts separate as alternative, but default (implicit) is usual choice.

If anything's missing, report it rather than silently patching.

### 5. Apply the pnpm composed-client workaround (pnpm only)

Skip for npm / yarn / bun — only pnpm needs it.

**Why**: default composed client emits to `node_modules/.vovk-client` and is re-exported by `vovk-client` package. pnpm's strict, non-hoisted `node_modules` layout breaks that re-export path. Documented fix: emit composed client to local project dir via `ts` template and drop `vovk-client` dep entirely.

Detect pnpm via `pnpm-lock.yaml` at project root (Path A) or scaffold w/ `--use-pnpm` (Path B default).

Apply four changes after `vovk init` completes:

1. **Patch `vovk.config.mjs`** — add `composedClient` block. Keep any existing `outputConfig` CLI wrote:

   ```js
   // @ts-check
   /** @type {import('vovk').VovkConfig} */
   const vovkConfig = {
     composedClient: {
       fromTemplates: ['ts'],
       outDir: './src/client',
     },
     outputConfig: {
       imports: {
         validateOnClient: 'vovk-ajv', // or whatever the CLI wrote
       },
     },
   };

   export default vovkConfig;
   ```

   For root-layout project (no `src/` dir — `app/` at repo root), use `outDir: './client'` and mirror in alias below.

2. **Ensure `@/client` path alias resolves in `tsconfig.json`**. Standard Next.js scaffold already has `compilerOptions.paths` containing `"@/*": ["./src/*"]` (or `["./*"]` for root layout), so `@/client` resolves to generated client automatically — no change needed. Check existing `paths`:

   - If `@/*` present and points to same root as `outDir` (`./src/*` paired w/ `outDir: './src/client'`, or `./*` paired w/ `outDir: './client'`) → done.
   - Otherwise, add **explicit** `@/client` entry so imports resolve regardless of how (or whether) `@/*` is wired:

     ```json
     {
       "compilerOptions": {
         "paths": {
           "@/*": ["./src/*"],
           "@/client": ["./src/client"]
         }
       }
     }
     ```

     Specific `@/client` entry takes precedence over wildcard, so safe to add alongside any existing `@/*`. Root-layout variant: `"@/client": ["./client"]`.

3. **Remove `vovk-client` from `package.json` `dependencies`**, then `pnpm install` to sync lockfile. Leave `vovk`, `vovk-cli`, and validation library alone.

4. **Tell user import path changed**: instead of `import { UserRPC } from 'vovk-client'`, use `import { UserRPC } from '@/client'`. Doc snippets and tutorials using `vovk-client` import need translating to this path.

Generated `src/client/` regenerates on every schema change — commit alongside `.vovk-schema/`. If project is (or will be) pnpm workspace / monorepo, workaround is effectively mandatory — hoisting problem multiplies across workspace packages.

### 6. Offer the follow-up steps

Summarize concisely: what got installed (incl. validation library from step 2), what changed, what scripts exist now, and — if pnpm — that composed client lives in `src/client/` and imports come from `@/client`. Then ask about two natural next steps — don't cascade silently.

**Step 6a — create the root segment?**

> "Vovk is installed. Want me to create the root API segment? That's `npx vovk new segment`, which writes `src/app/api/[[...vovk]]/route.ts` — the catch-all route that registers controllers."

If yes, run it and verify file was created. If no, stop.

**Step 6b — create a first module?**

Only after segment exists.

> "Segment's ready. Want me to scaffold a first module? Give me any name — `user`, `User`, `USER`, `user-profile`, `my_cool_product`, even 'the cool product' — and I'll normalize it to camelCase before passing it to the CLI. If you want the module in a specific (already-created) segment, say so (e.g. 'in the admin segment') and I'll prefix accordingly. I'll always generate a controller + service pair."

CLI's `<name>` arg is `[segmentPath/]moduleName`. Two rules:

- **`moduleName`** (after last `/`, or whole string when no slash) **must be camelCase**. Lowercase first token, TitleCase every subsequent token, strip non-alphanumeric separators. Examples: `USER` → `user`, `User` → `user`, `user-profile` → `userProfile`, `my_cool_product` → `myCoolProduct`, `THE COOL PRODUCT` → `theCoolProduct`, `MyUser` → `myUser`, `myUser` → `myUser` (unchanged).
- **`segmentPath`** (anything before last `/`) is existing segment's URL path — lowercase or kebab-case, slash-separated for nesting (`admin`, `user-portal`, `foo/bar`). **Not camelCase.**

Examples:
- User says "user" → `npx vovk new controller service user` (root segment).
- User says "My-User in the Admin segment" → `npx vovk new controller service admin/myUser`.
- User says "profile under foo/bar" → `npx vovk new controller service foo/bar/profile`.

Stop afterward — user may want to inspect diff or plan more modules before continuing.

## Path B — new Next.js project

### 1. Check Node first

Before scaffolding anything, run `node --version`. `vovk init` needs ≥ 22; `create-next-app` prefers modern Node too. If Node older, surface and let user upgrade first — scaffolding Next.js then failing at `vovk init` wastes their time.

### 2. Confirm scope

> "No Next.js project here. I can scaffold one with TypeScript, `src/`, Tailwind, Biome (not ESLint), and the App Router, then run `vovk init` on top. Create it in this directory, or a subdirectory? (If subdirectory, what name?)"

Wait for confirmation.

### 3. Pick a package manager

Default to **pnpm** unless user specifies otherwise. If they prefer bun/yarn/npm, honor that and swap `--use-*` flag in scaffold command accordingly.

### 4. Scaffold Next.js

```bash
pnpm create next-app@latest <project-name> \
  --typescript \
  --src-dir \
  --tailwind \
  --biome \
  --app \
  --use-pnpm \
  --import-alias "@/*"
```

Use `.` as project name when scaffolding into current dir. `--biome` is native `create-next-app` flag — sets Biome up as linter/formatter directly, no separate install needed. If `create-next-app` surfaces unrecognized prompt, accept default per interactive-prompts rule.

Note: `--biome` setup only applies here in greenfield flow. When adding Vovk to **existing** Next.js project (Path A), don't touch linter setup — whatever project already uses (ESLint, Biome, or none) is user's choice, swapping it is out of scope.

### 5. Run Vovk init

Continue from **Path A, step 2** (validation-library detection). Fresh scaffold has no `zod` / `valibot` / `arktype` installed yet, so detection falls through to **Zod** default unless user stated otherwise. Prereqs from Path A, step 1 already satisfied by fresh scaffold, so that check can be skipped.

---
> Source: [finom/vovk](https://github.com/finom/vovk) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->