init

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 ≥ 24.15 (Bun 1.4+ and Deno 2.9+ also run `vovk-cli`).
- **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 ≥ 24.15. You'll need to upgrade it yourself (`nvm install 24 && nvm use 24` 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 < 24.15**: 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`

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-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`; flags of a `next dev [flags]` script go after `--`). A `dev` script that runs more (`prisma generate && next dev`) gets the explicit form instead: `concurrently` runs it next to `vovk dev`, with `cross-env PORT=3000`. New `prebuild` script added running `vovk generate` (so RPC codegen runs before every `next build`); Yarn 2+ doesn't run `pre` scripts, so there `build` becomes `vovk generate && next build` instead. `start` left untouched.
- `.gitignore` gained the generated client dir (`src/client/` when the app is in `src/app`, otherwise `client/`). Client is regenerated by `prebuild`, no need to commit it; import via `@/client`.

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. Verify the `@/client` alias resolves

Composed client generates into `src/client/` when the app is in `src/app` (otherwise `client/`); canonical import is `@/client`. Standard Next.js scaffold already has `compilerOptions.paths` with `"@/*": ["./src/*"]` (or `["./*"]` for root layout), so nothing to do. If the project has no `@/*` alias or it points elsewhere, add an explicit entry:

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

Specific `@/client` entry takes precedence over wildcard, so safe alongside any existing `@/*`. Root-layout variant: `"@/client": ["./client"]`. Projects that refuse aliases can import via relative path instead.

### 6. Offer the follow-up steps

Summarize concisely: what got installed (incl. validation library from step 2), what changed, what scripts exist now, and that composed client generates into `src/client/` (gitignored, rebuilt by `prebuild`) with imports 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."

From finom/vovk, MIT.

More from finom/vovk