Generators

Scaffold a @kit package, a page with its server file, or an API route that already follows the kit rules, with pnpm kit:generate or the kit_generate tool.

pnpm kit:generate creates the files for a new package, page or API route, already wired the way the kit expects: session check in place, title from a message key, client and server entries split. Coding agents call the same thing as the kit_generate tool.

pnpm kit:generate package projects
pnpm kit:generate page projects
pnpm kit:generate page projects/[id]
pnpm kit:generate route projects/[id] --methods get,post

A generator only creates files. If one of its files already exists, it stops and writes nothing, so running it twice is safe. Add --json for a machine-readable result.

What Each One Writes

CommandFilesAccess
package <name>packages/<name>/: package.json, tsconfig.json, AGENTS.md, CLAUDE.md, src/index.ts, src/server.tsn/a
page <path>apps/web/pages/(app)/<path>.tsx and <path>.server.tsSigned-in
page <path> --publicapps/web/pages/<path>.tsx and <path>.server.tsPublic
route <path>apps/web/routes/api/<path>.tsSigned-in
route <path> --publicapps/web/routes/api/<path>.tsPublic

Paths use lowercase segments, [param] and a trailing [...rest], as Void's file router reads them, and need at least one plain segment. Quote a path with brackets in zsh: 'projects/[id]'.

Package

pnpm kit:generate package projects

The package is named @kit/projects. src/index.ts is the entry that is safe for the browser, src/server.ts (imported as @kit/projects/server) is server-only. Then:

  1. Add "@kit/projects": "workspace:*" to the dependencies of apps/web/package.json, or of the package that uses it.
  2. Run pnpm install.
  3. Write the package's own rules in packages/projects/AGENTS.md as you build it.

A package never imports void/*. It takes db, tables, auth and settings as parameters, and the app binds them in apps/web/config/*.server.ts. Tests go in src/__tests__/.

Page

pnpm kit:generate page projects/index

This writes pages/(app)/projects/index.server.ts and index.tsx, served at /projects. The loader calls requireSession({ c }) before anything else, and the page renders inside the app shell with the breadcrumb header.

The title is the message key app:projects.title. Until you add it, the page shows the key itself. Add it with the app_translations_update tool, or in apps/web/messages/en/app.json:

{
"projects": {
"title": "Projects"
}
}

Next steps:

  • Load data in the loader, after requireSession. Organization data needs requireActiveOrganization({ c }) (Scoping Data).
  • To list the page in the sidebar, add it to apps/web/config/navigation.config.tsx (Navigation).

--public puts the page outside (app)/ and leaves the session check out. Never return a signed-in user's data from a public loader.

Route

pnpm kit:generate route projects/[id] --methods get,post

This writes routes/api/projects/[id].ts with one defineHandler export per method (get when you give none; get, post, put, patch, delete are accepted). Each handler calls requireSession({ c }) first, so a signed-out request gets 401.

Next steps:

  • Authorize beyond the session inside each handler: organization, role, ownership.
  • Validate input with withValidator and keep the logic in a *.service.ts.
  • Put the route's tests in apps/web/tests/routes/, not beside the route: Void loads every .ts file in routes/.

Use a route only for endpoints that are not a page: webhooks, uploads, JSON for a client. A form on a page posts to that page's action instead.

--public leaves the session check out. Rate-limit a public route with limitRequest (Rate Limits).

What Is Not Generated

You wantUse
An admin pageAdding Admin Pages: it needs requireAdmin and server-only copy
A marketing pageAdding a Page: it is cached and skips the nonce CSP
A tableEdit apps/web/db/schema.ts, then pnpm --filter web exec void db generate
A background job or a scheduleJobs and Schedules

The generator also refuses:

  • Paths the kit owns and guards differently: pages under admin/, auth/ and api/, and routes under admin/, auth/, files/, uploads/, health and client-errors.
  • A URL another file already serves: page dashboard is refused because pages/(app)/dashboard/index.tsx exists, and projects and projects/index count as the same page.
  • Paths the router can't read: a [...rest] segment that isn't last, or the same [param] name twice.

Don't use void gen route or void gen model: their output skips the session check and the kit's migration workflow.

Common Pitfalls

  • Dependency not added. A generated package is not installed anywhere until you add it to a package.json and run pnpm install.
  • The page shows app.projects.title. The message key is missing: add it.
  • --public on a page that reads the session. The folder decides access: move the files under pages/(app)/ and call requireSession instead.
  • Nothing was written. One of the files already exists. The message lists which.