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 projectspnpm kit:generate page projectspnpm kit:generate page projects/[id]pnpm kit:generate route projects/[id] --methods get,postA 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
| Command | Files | Access |
|---|---|---|
package <name> | packages/<name>/: package.json, tsconfig.json, AGENTS.md, CLAUDE.md, src/index.ts, src/server.ts | n/a |
page <path> | apps/web/pages/(app)/<path>.tsx and <path>.server.ts | Signed-in |
page <path> --public | apps/web/pages/<path>.tsx and <path>.server.ts | Public |
route <path> | apps/web/routes/api/<path>.ts | Signed-in |
route <path> --public | apps/web/routes/api/<path>.ts | Public |
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 projectsThe 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:
- Add
"@kit/projects": "workspace:*"to thedependenciesofapps/web/package.json, or of the package that uses it. - Run
pnpm install. - Write the package's own rules in
packages/projects/AGENTS.mdas 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/indexThis 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 needsrequireActiveOrganization({ 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,postThis 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
withValidatorand keep the logic in a*.service.ts. - Put the route's tests in
apps/web/tests/routes/, not beside the route: Void loads every.tsfile inroutes/.
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 want | Use |
|---|---|
| An admin page | Adding Admin Pages: it needs requireAdmin and server-only copy |
| A marketing page | Adding a Page: it is cached and skips the nonce CSP |
| A table | Edit apps/web/db/schema.ts, then pnpm --filter web exec void db generate |
| A background job or a schedule | Jobs and Schedules |
The generator also refuses:
- Paths the kit owns and guards differently: pages under
admin/,auth/andapi/, and routes underadmin/,auth/,files/,uploads/,healthandclient-errors. - A URL another file already serves:
page dashboardis refused becausepages/(app)/dashboard/index.tsxexists, andprojectsandprojects/indexcount 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.jsonand runpnpm install. - The page shows
app.projects.title. The message key is missing: add it. --publicon a page that reads the session. The folder decides access: move the files underpages/(app)/and callrequireSessioninstead.- Nothing was written. One of the files already exists. The message lists which.