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:

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:

   // @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:

     {
       "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

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.