# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/development-guide/generators*

---

`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.

```bash
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

| 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

```bash
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

```bash
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`:

```json
{
  "projects": {
    "title": "Projects"
  }
}
```

Next steps:

- Load data in the loader, after `requireSession`. Organization data needs `requireActiveOrganization({ c })` ([Scoping Data](../organizations/scoping-data)).
- To list the page in the sidebar, add it to `apps/web/config/navigation.config.tsx` ([Navigation](../configuration/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

```bash
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](../operations/rate-limits)).

## What Is Not Generated

| You want | Use |
|---|---|
| An admin page | [Adding Admin Pages](../admin/adding-admin-pages): it needs `requireAdmin` and server-only copy |
| A marketing page | [Adding a Page](../marketing/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](../outbox/jobs) and [Schedules](../outbox/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.
