This is the abridged developer documentation for Seaforms
# Your forms, in your own code.
> Put Seaforms forms in a site built with code. The React package for React, Next.js, React Router and Astro, the seaforms CLI, signed webhooks, the API, the form format and the MCP connector for AI tools.
# Introduction
> What a site built with code can do with Seaforms. Draw a published form in your page with the React package, pull it with the CLI or fetch it while you build, get each submission by webhook, and work with your forms through the API or an AI tool.
Seaforms is a form builder. You, a colleague or a client build a form in the app at [app.seaforms.io](https://app.seaforms.io) and publish it. These docs are for the developer who puts that form in a site built with code: React, Next.js, Astro, or a site an AI tool built. ## How a form gets to your page A published form is a file: its questions, steps, logic and thank-yous as JSON, such as `src/forms/contact.seaforms.json`. Your site reads it while it builds, and `@seaforms/react` draws it. * **In your page’s HTML.** The form renders on your server as a real `
```
`client:load` draws the form in the HTML and wakes it as the page loads. See [Astro](/react/astro/) for `client:visible` and pages with no script at all. * React src/Contact.tsx
```tsx
import { Form } from "@seaforms/react";
import contact from "./forms/contact.seaforms.json";
export function Contact() {
return ;
}
```
Render it on the server where you can, so the form is in the page’s HTML before JavaScript loads. A page drawn only in the browser still works, but shows nothing until its script runs. 6. **Add your site’s addresses.** In the app, go to **Settings**, then **Site details**, and add every address the site is served from under **Addresses**, such as `https://northwind.co` and `https://www.northwind.co`. A submission from an address that isn’t on the list is still kept, but as spam, so a copied form can’t fill your inbox. 7. **Try it on your computer.** Make a dev token under **Dev tokens** in **Site details**, and pass it while you work: Your page
```tsx
```
On `localhost`, answers sent with it are tests: kept apart from real ones and never counted against your plan. See [Try it on your computer](/react/testing/). ## The file you pulled `src/forms/contact.seaforms.json` holds the form’s questions, steps and logic. You never edit it: change the form in the app, publish, and pull again. src/forms/contact.seaforms.json
```json
{
"schemaVersion": 1,
"id": "frm_7f3kq2m4xa",
"revision": 3,
"locale": "en-AU",
"timezone": "Australia/Adelaide",
"presentation": {
"mode": "steps",
"progress": {
"bar": false,
"time": true
},
"labels": {
"next": "Continue",
"back": "Back",
"submit": "Send message"
},
"estimatedSeconds": 60,
"requiredMarker": "optional-label",
"badge": false
},
"steps": [
{
"id": "get-in-touch",
"title": "Get in touch",
"blocks": [
{
"kind": "field",
"key": "name",
"label": "Name",
"placeholder": "Maya Chen",
"required": true,
"autocomplete": "name",
"type": "text"
},
{
"kind": "field",
"key": "email",
"label": "Email",
"placeholder": "maya@northwind.co",
"required": true,
"autocomplete": "email",
"type": "email"
},
{
"kind": "field",
"key": "topic",
"label": "What’s it about?",
"required": true,
"type": "choice",
"display": "chips",
"options": [
{
"value": "sales",
"label": "Sales"
},
{
"value": "support",
"label": "Support"
},
{
"value": "press",
"label": "Press"
},
{
"value": "something-else",
"label": "Something else"
}
]
},
{
"kind": "field",
"key": "message",
"label": "Message",
"placeholder": "How can we help?",
"required": true,
"type": "textarea"
}
]
}
],
"endings": [
{
"id": "thanks",
"title": "Thanks, {name}.",
"body": "Your message is with the right person. We usually reply the same day."
}
],
"features": [],
"initial": {
"hidden": [],
"alwaysRequired": [
"name",
"email",
"topic",
"message"
]
},
"hash": "3096824560e56c78"
}
```
## Next * [Next.js](/react/nextjs/), [React Router](/react/react-router/) or [Astro](/react/astro/): fetch the form while your site builds instead, so a client’s publish needs no pull. * [Styling](/react/styling/): your own classes, or our finished look. * [Webhooks](/webhooks/): each submission at your own endpoint.
# Set up with AI
> Hand these docs to a coding agent such as Claude Code or Cursor and let it put your Seaforms forms in your site. The llms.txt files, and a prompt for Next.js, React Router and Astro.
Putting a form in a site is one package, two commands and a component, which makes it a good job for a coding agent. These docs are published in a form an agent can read in one go. ## The files an agent reads | File | What it holds | | ------------------------------------ | --------------------------------------------------------------------------- | | [`/llms.txt`](/llms.txt) | A short map of these docs, with links. | | [`/llms-full.txt`](/llms-full.txt) | Every page in one file. Point an agent here when you want it to write code. | | [`/llms-small.txt`](/llms-small.txt) | The same, trimmed for a smaller context. | ## A prompt for your framework Copy one and paste it into Claude Code, Cursor or any coding agent. Publish the form in the app first: an agent only ever sees published forms. * Next.js Hand this to your coding agent
```
Read https://developer.seaforms.io/llms-full.txt.
Install @seaforms/react in this Next.js (App Router) project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in src/forms with their types.
Then add the contact form to app/contact/page.tsx with the Form component.
Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files.
```
* React Router Hand this to your coding agent
```
Read https://developer.seaforms.io/llms-full.txt.
Install @seaforms/react in this React Router (Framework mode) project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in forms with their types.
Then add the contact form to app/routes/contact.tsx with the Form component.
Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files.
```
* Astro Hand this to your coding agent
```
Read https://developer.seaforms.io/llms-full.txt.
Install @seaforms/react in this Astro project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in src/forms with their types.
Then add the contact form to src/pages/contact.astro with the Form component and client:load.
Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files.
```
### When a client edits the form If someone else publishes the form’s changes, have the agent fetch it while the site builds instead of keeping its file. Put your form’s ID in place of ``, and set `SEAFORMS_API_KEY` yourself (an [API key](/react/#the-key) that can only read forms): * Next.js Hand this to your coding agent
```
Read https://developer.seaforms.io/llms-full.txt.
Install @seaforms/react in this Next.js (App Router) project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code.
Then show the form on app/quote/page.tsx, checking for a newly published version at most once an hour.
Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files.
```
* React Router Hand this to your coding agent
```
Read https://developer.seaforms.io/llms-full.txt.
Install @seaforms/react in this React Router (Framework mode) project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code.
Then show the form on app/routes/quote.tsx, calling getForm in the route's loader, and add /quote to prerender in react-router.config.ts.
Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files.
```
* Astro Hand this to your coding agent
```
Read https://developer.seaforms.io/llms-full.txt.
Install @seaforms/react in this Astro project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code.
Then show the form on src/pages/quote.astro, with the key read through astro:env as a server secret.
Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files.
```
## Let the agent build the form too With the [MCP connector](/mcp/), a coding tool such as Claude Code or Cursor can make the form itself, publish it and save its file in your code, so you never leave the editor. You choose what it may do when it connects, and it can’t delete anything.
```sh
claude mcp add --transport http seaforms https://mcp.seaforms.io/mcp
```
See [Claude Code](/mcp/claude-code/) or [Cursor, VS Code and others](/mcp/other/) for signing it in.
# Install the React package
> Install @seaforms/react for React, Next.js, React Router and Astro. What it draws, what it sends, its three entry points, and the Content Security Policy it needs.
`@seaforms/react` draws a published Seaforms form as part of your page. It needs React 18.2 or later, and works in anything that renders React: Next.js, Astro with its React integration, [React Router](/react/react-router/) in Framework mode, Remix, or a plain React app. * npm
```sh
npm install @seaforms/react
```
* pnpm
```sh
pnpm add @seaforms/react
```
* yarn
```sh
yarn add @seaforms/react
```
* bun
```sh
bun add @seaforms/react
```
ContactPage.tsx
```tsx
import { Form } from "@seaforms/react";
import contact from "./forms/contact.seaforms.json";
;
```
`schema` is the [form’s file](/format/), pulled with [`npx seaforms pull`](/cli/) or fetched while your site builds with [`getForm`](#getform). ## What it draws * **A real HTML form, on your server.** It’s in the page’s HTML before any JavaScript loads, with a real `