@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 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 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.
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:
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.
Editing a record
Give the blueprint an update, and <profile.Form /> with an id edits that
record instead of creating one, starting from values:
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))
},
})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:
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. 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:
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.
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:
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:
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.
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'],
];
}
}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.
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:
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.
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 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:
theme: { ...shadcn, BlueprintForm: MyForm },