Resource generator

Most SaaS features start with the same work: a table, create/read/update/delete actions scoped to the user or the organization, a form, a list and a detail page. pnpm resource:generate writes all of it from a short JSON spec, using the shared components of the resource kit. You then own the generated code and customize it like any other file.

The boilerplate also ships two hand-written CRUD examples, categories and projects, that show the same patterns without the generator.

Where the code lives

Quick start

The repository includes the spec of the organization projects example:

{
  "name": "orgProject",
  "title": "Projects",
  "scope": "organization",
  "icon": "FolderKanban",
  "labelField": "name",
  "fields": [
    { "name": "name", "type": "text", "required": true, "searchable": true },
    { "name": "description", "type": "textarea" },
    {
      "name": "status",
      "type": "select",
      "options": ["planned", "active", "paused", "done"],
      "defaultValue": "planned"
    },
    { "name": "dueDate", "type": "date" }
  ]
}

It produced the Projects page of every organization (/orgs/<slug>/org-projects). To create your own resource:

{
  "name": "bookmark",
  "title": "Bookmarks",
  "path": "/bookmarks",
  "icon": "Bookmark",
  "labelField": "title",
  "fields": [
    { "name": "title", "type": "text", "required": true, "searchable": true },
    { "name": "url", "type": "url", "required": true },
    { "name": "notes", "type": "textarea" },
    { "name": "favorite", "type": "boolean" },
    {
      "name": "categoryId",
      "type": "relation",
      "targetResource": "category",
      "targetLabelField": "name"
    }
  ]
}

pnpm resource:generate --spec drizzle/resources/bookmarks.json

pnpm db:generate
pnpm db:migrate

Run the command without --spec to answer the same questions interactively: name, title, scope, admin-only, path, icon, then each field (name, type, required, options or relation target, searchable). An empty field name ends the list.

Options

A spec file holds one resource, or several under a resources key:

{ "resources": [{ "name": "author", "fields": ["name"] }, { "name": "book", "fields": ["title"] }] }

A field can be written as a plain string, which creates an optional text field.

Spec keys

Default paths:

• User scope: /<name in kebab-case>, singular (bookmark becomes /bookmark), or /admin/<name> with adminOnly. Set path to use a plural URL.
• Organization scope: /orgs/[orgSlug]/<plural kebab name> (orgProject becomes /orgs/[orgSlug]/org-projects). A custom path is the segment after /orgs/[orgSlug].

adminOnly and "scope": "organization" can't be combined.

Field keys

The names id, userId, organizationId, createdAt and updatedAt are reserved: those columns are added automatically.

Field types

Optional fields accept empty values, which are saved as null.

A relation field references the target table's id. When the field is required, deleting the target deletes the row (cascade); otherwise the reference is set to null. The target table must already exist in drizzle/auth-schema.ts or be generated in the same run. Name relation fields with an Id suffix (categoryId), so the Drizzle relation gets a clean name (category).

What gets generated

For the bookmark spec above:

The sidebar link goes to dashboard.tsx (user scope), admin.tsx (adminOnly) or organization.tsx (organization scope, right after "Overview"). Admin pages don't get a layout because app/(app)/admin/layout.tsx already redirects non-admins; organization pages rely on the app/(app)/orgs/[orgSlug] layout.

The table

Every generated table has a text id defaulting to randomUUID(), a userId foreign key to user with cascade delete, createdAt and updatedAt timestamps, and an index on userId. Organization-scoped tables also get organizationId (cascade delete, indexed). userId then records the creator.

The actions

The generated actions follow the rules of Server actions:

• User scope: every query filters by ctx.user.id. Mutations call revalidatePath on the list and detail pages.
• Organization scope: every action takes organizationId, calls requireMembership() and filters by organization. Any member can list, read, create and update; deleting requires the owner or admin role. Mutations call revalidateOrganization().
• Writes only keep the fields declared in the spec (pickFieldValues()), so a client can't set userId, organizationId or timestamps.
• Relation values are checked: the target row must belong to the same user or organization, otherwise the action throws "Invalid category".
• Both delete actions use nonDemoAction, so the shared demo account can't delete data. Bulk delete accepts up to 100 ids.

The UI

ResourceTable renders, from the field list:

• A search box over the searchable fields (or, if none is marked, every text, textarea, email, url and select field).
• A faceted filter per select field, column visibility, sortable columns and pagination.
• Row selection with bulk delete, and edit and delete row actions. Both deletes ask for confirmation: the row action through the dialog manager, the bulk delete in an alert dialog.
• Cells formatted by type: badges for booleans and selects, dates without timezone shift, masked passwords.

ResourceFormSheet builds the form with useZodForm() and the generated insert schema, renders one ResourceFieldInput per field, shows server validation errors inline, and loads relation options when it opens. ResourceDetail lists every field of a record on the detail page.

Run it again

Running the generator again for the same name:

• Skips existing files, unless you pass --force, which overwrites them.
• Replaces the table definition in drizzle/auth-schema.ts with the one from the spec.
• Updates the manifest entry.
• Leaves the sidebar alone if a link to the same URL exists.

Customize a generated resource

The generated code is yours. Common changes:

• Labels and page text: edit the page files, or title and singular in lib/<name>-config.ts.
• Validation: the schemas come from buildInsertSchema() and buildUpdateSchema() in lib/resource-kit/zod.ts. Replace them in the config file with your own Zod schemas for rules the spec can't express.
• Business rules: add checks, notifications or side effects in lib/<name>-actions.ts.
• Table columns and actions: pass props to ResourceTable (emptyTitle, emptyDescription, canDelete, renderCreate), or copy it into your feature folder when you need a very different table.
• New columns later: add them to drizzle/auth-schema.ts and to the fields array in the config file, then generate a migration.

Reference implementation: categories and projects

Categories and projects are a hand-written, user-scoped CRUD example. Use them when you want full control over the UI instead of the resource kit.

Differences with generated resources:

• Data loading: pages fetch the list on the server and pass it as initial props (await listCategories() then <CategoriesTable initialCategories={...} />); mutations call revalidatePath. Generated resources load and refresh through TanStack Query.
• Tables: written with the useLegacyTable API of TanStack Table and their own columns, filters and empty states.
• Forms: dedicated schemas and inputs (NativeSelect for the status and category), wired with useAction and applyValidationErrors().
• Ownership checks: projects-actions.ts verifies that the selected category belongs to the user (assertCategoryOwned) and throws Project not found when a row doesn't match. See Server actions for the pattern.

Remove the examples

Categories, projects, organization projects and the demo page are examples. pnpm reset-project moves them to examples/ (kept as reference and excluded from the build), removes the code between @reset-remove:start and @reset-remove:end markers (tables, sidebar links) and clears the manifest. Run pnpm reset-project --dry-run first to see what it would change, then generate a migration to drop the example tables.