---
title: "Blueprints"
description: "A form defined once - fields, checks and saves - and drawn anywhere it is needed - a contact page, an edit page, an admin panel - from a Standard Schema or a backend's own actions."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.rsc-kit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprints

`@rsc-kit/press/forms` turns a Standard Schema, or a backend's actions, into a
**blueprint**: a form's fields, its checks and what saving it does, defined
once. A page draws it with `<contact.Form />`, an edit page with
`<profile.Form id={user.id} values={user} />`, and an
[admin panel](/guides/admin/) draws its create and edit pages from it with
`defineResource({ form: profile })` - the same fields, the same browser
checks, the same refusals under the same fields. A
[theme](/guides/admin/#themes) draws it; the `shadcn` theme draws both.

On a Laravel or Go backend there is no schema to write: hand it the backend's
actions, and the form is drawn from what they take. See
[A Laravel or Go backend](#a-laravel-or-go-backend).

```ts title="src/forms/contact.ts"
import * as z from 'zod'
import { defineBlueprint } from '@rsc-kit/press/forms'
import { shadcn } from '@rsc-kit/press/shadcn'

export const contact = defineBlueprint({
  name: 'contact',
  form: z.object({
name: z.string().min(2),
email: z.email(),
message: z.string().min(10).max(2000),
  }),
  fields: { message: { type: 'textarea' } },
  theme: shadcn,
  submit: 'Send message',
  done: 'Thanks - we will be in touch.',
  handle: async (values) => {
await db.insert(messages).values(values)
  },
})
```

Place it in any page:

```tsx title="src/app/contact/page.tsx"
import { contact } from '@/forms/contact'

export default function ContactPage() {
  return (
<main>
  <h1>Contact us</h1>
  <contact.Form />
</main>
  )
}
```

The form reads nothing from the request, so the page around it is stored by
the build like any other static page. Only sending it runs on the server.

Install is the panel's: `bun add @rsc-kit/press`, and the
`@import "@rsc-kit/press/shadcn.css"` line in the app's stylesheet, as in
[Admin panels](/guides/admin/#install).

## Editing a record

Give the blueprint an `update`, and `<profile.Form />` with an `id` edits that
record instead of creating one, starting from `values`:

```ts title="src/forms/profile.ts"
export const profile = defineBlueprint({
  name: 'profile',
  form: z.object({ name: z.string().min(2), email: z.email() }),
  theme: shadcn,
  honeypot: false,
  done: 'Saved.',
  update: async (values, key) => {
await db.update(users).set(values).where(eq(users.id, key))
  },
})
```

```tsx title="src/app/settings/page.tsx"
export default async function Settings() {
  const user = await currentUser()

  return <profile.Form id={user.id} values={user} />
}
```

Only the blueprint's own fields of `values` reach the browser, so handing it
a whole row does not put its password hash in the page.

**The key comes back from the browser**, like every field, and anyone can post
another. `update` must check the visitor may change that record - here, by
comparing it with the session's user; in Laravel, the `FormRequest`'s
`authorize()`. A blueprint may have `handle`, `update` or both, and drawing it
for one it does not have says so.

`honeypot: false` drops the bot trap for a form only signed-in people reach.

## In an admin panel

A resource takes the blueprint as its `form`, and its create and edit pages are
that blueprint's form:

```ts
export const people = defineResource<User>()({
  name: 'people',
  key: 'id',
  title: 'name',
  source: { list, find, delete: remove },
  table: (col) => [col.text('name'), col.text('email')],
  form: profile,
})
```

A blueprint that saves - a backend's `create` and `update`, or a schema's
`handle` and `update` - saves the panel's records too, so the source only
lists, finds and deletes. One that does not leaves saving to a whole
[source](/guides/admin/). `fields` and `actions` are said on the blueprint,
not again on the resource.

## What is checked, and where

The schema's constraints become the browser's - `required`, `minlength`,
`maxlength`, `type="email"`, a `pattern` - so a visitor hears about a missing
field before anything is sent, under the field, in their own language. The
schema then checks every submission on the server, which is the check that
counts: anyone can post without a browser. What it refuses comes back under
each field, with what was typed kept.

`handle` gets the values only once they have passed. A refusal it decides -
an address already signed up - goes under its field the same way:

```ts
import { fieldErrors } from '@rsc-kit/core/action'

handle: async ({ email }) => {
  if (await subscribed(email)) fieldErrors({ email: 'That address is already on the list.' })
  await subscribe(email)
},
```

## Fields that depend on others

Two things a field can say about another, in `fields`, as plain data: the
browser applies them while the visitor types, and the server applies them again
to what was sent.

```ts
fields: {
  company: { visible: { when: 'topic', is: 'sales' } },
  slug: { from: { field: 'title' } },
},
```

**`visible`** shows a field only while another has one of the values in `is` -
one value or a list. `not` turns it round, and with neither the field shows
once the other is filled in, or a switch is on. A hidden field is not sent, and
the browser does not check it; if a post sends one anyway, the server drops it
before the schema sees it. So a field asked only sometimes is optional to the
schema - `z.string().min(2).optional()` - and checked whenever it is there.

**`from`** fills a field with the slug of another - "Café & Bar" is
`cafe-bar` - as the other is typed. Once someone edits it by hand it is left
alone, and one left empty is filled the same way on the server.

`when` and `field` name another of the form's fields, and one that does not
exist fails at startup.

## A Laravel or Go backend

Give it the backend's actions, and the form needs no schema of its own. The
backend already says what each takes, so the fields and the browser's checks
come from there, and every check that counts is the backend's. The actions are
the ones the build generated, imported like any other:

```ts title="resources/js/forms/contact.ts"
import { defineBlueprint } from '@rsc-kit/press/forms'
import { shadcn } from '@rsc-kit/press/shadcn'
import { contactSend } from '../server-actions.generated'

export const contact = defineBlueprint({
  name: 'contact',
  actions: { create: contactSend },
  fields: { message: { type: 'textarea' } },
  theme: shadcn,
  submit: 'Send message',
  done: 'Thanks - we will be in touch.',
})
```

`actions` is `{ create, update }`, either or both. The create form is drawn
from what `create` takes and the edit form from what `update` takes, so a
password required to sign up can be optional to edit. `update` is called with
the record's key after the values: `update(UpdateProfile $request, string
$user)` in Laravel, where `$this->route('user')` reads it in `rules()` and
`authorize()`, and `func(ctx, in ProfileInput, id string)` in Go.

You need not write it: `bunx rsc-kit make:form contactSend` writes this file
from the action, and it is yours to edit from then on.

An action that is not there fails the import, and a field `fields` names that
the action does not take fails the typecheck. `fields` still sets a label or a control, and the bot trap, `done`
and `redirect` work as on any form. There is no `handle`: the values go to the
function. Nothing reaches the browser but the form, and no validation library
is added to the server.

The action must take one object with named fields: a `FormRequest` in Laravel,
a struct in Go. A form given anything else says so when it first renders, as
does one given a function the build did not generate. So
does a field it cannot draw, such as a file: an action's values travel as JSON,
so an upload needs `form` and `handle`. Give an open-typed field a control in
`fields`.

To check something in TypeScript first, or to shape the values on the way, keep
a schema and call the backend yourself:

```ts
form: z.object({ email: z.email() }),
handle: (values) => contactSend(values),
```

The schema's checks then run first, so a submission it refuses never reaches the
backend.

The values arrive as one object, keyed by field. What the backend refuses comes
back under the field of the same name, with what was typed kept, and there is
nothing to catch.

### Laravel

A `FormRequest` type-hinted on the method is built from the values and validated
before the method runs, as on a route. Its failure is the 422 the form reads.

```php title="app/Http/Requests/SendContact.php"
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class SendContact extends FormRequest
{
public function authorize(): bool
{
    return true; // anyone may send it; make:request writes false
}

public function rules(): array
{
    return [
        'name' => ['required', 'string', 'min:2'],
        'email' => ['required', 'email', 'unique:subscribers,email'],
        'message' => ['required', 'string', 'min:10', 'max:2000'],
    ];
}
}
```

```php title="app/Rsc/Actions/Contact.php"
namespace App\Rsc\Actions;

use App\Http\Requests\SendContact;
use App\Models\Message;

class Contact
{
public function send(SendContact $request): void
{
    Message::create($request->validated());
}
}
```

The method takes the request alone. Without a `FormRequest`, take `array $values`
and call `Validator::make($values, [...])->validate()`, or throw
`ValidationException::withMessages(['email' => 'That address is blocked.'])`.
Either lands the same way.

Keep the class under `app/Rsc/Actions`, where every public method is an action:
`Contact::send` is `contactSend`, generated at the next build.

The form's fields are read from `rules()`, in order, at build time: `required`,
the type rules, `email`, `url`, `date`, `min`, `max`, `size`, `between`, and
`in` or `Rule::in()`, which draws a select. Anything else stays the server's
check alone, and its field a plain input: `regex` (PCRE is not the browser's
pattern), `Rule::enum()`, a closure. `rules()` runs with no request behind it,
so one that reads the request cannot be described: list the fields in `fields`.

`required_if:topic,support` is read as `visible`: the field shows while `topic`
is `support`, or any of the values listed after it, and is required then.

`rsc:install` does not set up Tailwind or shadcn, so the `shadcn` theme comes out
unstyled until the app has both.

### Go

Register an action that takes the values as a struct. Its `json` tags are the
form's field names, and `rsckit.InvalidField` or `rsckit.Invalid` is the 422.

```go
type ContactInput struct {
Name    string `json:"name"`
Email   string `json:"email"`
Message string `json:"message"`
}

reg.HandleAction("contactSend", "Contact.send", func(ctx context.Context, in ContactInput) error {
if blocked(in.Email) {
    return rsckit.InvalidField("email", "That address is blocked.")
}

return messages.Insert(ctx, in)
})
```

For several fields at once:

```go
return rsckit.Invalid(map[string][]string{
"email":   {"That address is blocked."},
"message": {"That looks like spam."},
})
```

`reg.WriteManifest("rsc-host.json")` puts it in the manifest, and the build
generates `contactSend` from it, as for any action.

The form's fields are the struct's, in its order, and a field is required unless
its `json` tag says `omitempty`. A `validate` tag, in go-playground/validator's
spelling, adds what the browser can check: `required`, `omitempty`, `email`,
`url`, `min`, `max`, `len`, `gte`, `lte`, `oneof` (a select) and
`datetime=2006-01-02`. `required_if=Topic support` is read as `visible`: the
field shows while `topic` is `support`, and is required then. Only one field and
one value - several pairs must all hold, which a form cannot show as one.

```go
type ContactInput struct {
Name    string `json:"name" validate:"required,min=2"`
Email   string `json:"email" validate:"required,email"`
Topic   string `json:"topic" validate:"required,oneof=sales support"`
Message string `json:"message" validate:"required,min=10,max=2000"`
}
```

**The tag is only read, never run.** `rsc-kit/go` depends on no validator, so
the function still checks what it was sent, with validator or by hand: a post
need not come from a browser.

### On a kept page

A blueprint's form can sit in an [ISR](/guides/isr) page. The page is kept for
everyone, and the post is the visitor's own: it needs no token, because the
engine and Laravel 13 accept a same-origin post by its `Sec-Fetch-Site` header.
The call to the backend runs in that post, so it carries the visitor's cookie,
unlike the calls the kept page made while rendering.

## Once it is sent

`done` is what the visitor reads in place of the form; without one it says
the message was sent. `redirect` sends them somewhere instead - a thank-you
page, the account they just made - and a form has one or the other, not both.

## Bots

Every form carries a field people never see: off screen, out of the tab order,
hidden from screen readers and not autofilled. A bot filling in every input
fills that one too, and the submission is answered as though it worked and
dropped - `handle` never sees it, and the bot learns nothing. It is a filter
for the crudest spam, not a CAPTCHA; a form worth attacking wants rate
limiting as well.

A backend is told the visitor's address on every call, so `throttle:5,1` on
the action limits each visitor on their own - `$request->ip()` in Laravel,
`rsckit.ClientIP(ctx)` in Go. Behind a load balancer or Cloudflare, set
`RSC_TRUST_FORWARDED=1` on the renderer, or every visitor arrives as the
balancer. Limiting at the CDN as well spares the backend the work.

The trap is named `homepage`, so a form cannot have a field of that name.

## Drawing it yourself

The theme's part is one component, `BlueprintForm`, typed `FormsTheme` from
`@rsc-kit/press/forms`. It is given the bound `action`, the `fields`, the
starting `values`, the `submit` words, `done`, and the `honeypot` field's
name to render hidden - absent when the blueprint turned it off. Replace it
as you would a panel page:

```ts
theme: { ...shadcn, BlueprintForm: MyForm },
```

Source: https://docs.rsc-kit.dev/guides/blueprints/index.mdx
