Fillo

View saved version →

---
name: build-with-fillo
description: Build, embed, style, sync, and verify product-native Fillo forms in React, Next.js, Vue, Svelte, Astro, or browser apps. Use when a task mentions Fillo, @usefillo packages, a Fillo form id or slug, a Build with AI handoff, a publishable key, form schema authoring, prefill, uploads, respondents, webhooks, integrations, or troubleshooting a Fillo form. Do not use for contributing to the Fillo monorepo itself.
---

# Build with Fillo

Add a real form inside the host product. Keep the host app in control of its
route, layout, components, account context, and post-submit behavior. Let Fillo
own schema, validation, uploads, responses, versions, exports, and delivery.

Use the repository, browser, and test tools available in the current agent.
Never require a provider-specific agent command.

## Work in this order

1. Inspect the host repository. Identify its framework, package manager, target
   route, UI conventions, existing Fillo packages, and any supplied form id,
   key, setup command, or run token.
2. Establish the form's source of truth:
   - Published form id or slug: render it directly. No client key is required.
   - React-owned schema: use `<Fillo.Form>` or `defineForm()` with
     `@usefillo/react`.
   - Vue, Svelte, Astro, or browser-owned schema: use `defineForm()` and
     `renderForm()` from `@usefillo/dom`.
   - Dashboard or CLI-owned schema: keep the schema there and embed the returned
     `formId`.
   - Fully custom UI: use `FilloProvider` and hooks in React, or
     `createFormController()` elsewhere.
   Every interactive embed must have exactly one submission identity: a
   published `formId`, or a `defineForm()` / `<Fillo.Form>` value plus a
   client. A plain `FormSchema` plus a client is not a code-defined form and
   cannot resolve a target. Use explicit `renderOnly` only for a deliberately
   non-submitting UI preview.
3. Ask only for missing product decisions that change the result: purpose,
   placement, required questions or files, conditional behavior, and what
   happens after submit. Infer routine implementation details from the repo.
4. If the prompt supplies a handoff command, workspace key, form id, or run
   token, follow that handoff exactly. Do not create a second workspace or save
   a run token.
5. Implement the smallest complete form, verify it in the host app, and report
   any remaining dashboard action honestly.

## Load only the needed reference

- React, Next.js, DOM, custom elements, headless rendering, or styling:
  [references/frameworks.md](references/frameworks.md)
- Field choice, stable ids, conditional logic, prefill, and form UX:
  [references/schema-and-ux.md](references/schema-and-ux.md)
- Provisioning, claiming from the terminal, scoped keys, staging, publishing,
  agent run events, agent mode, and security boundaries:
  [references/auth-and-lifecycle.md](references/auth-and-lifecycle.md)
- Uploads and CLI storage, verified respondents, webhooks, form settings,
  reading responses, or response destinations:
  [references/operations.md](references/operations.md)
- Runtime or integration failures:
  [references/troubleshooting.md](references/troubleshooting.md)
- Exact live guides and the API reference:
  [references/source-map.md](references/source-map.md). If a Fillo MCP server
  is already connected, see the tool mapping there.

Prefer sources in this order when they disagree:

1. Types and exports from the installed package version.
2. Live Fillo Markdown docs for the behavior being changed.
3. Bundled references for workflow and safety decisions.

Do not browse every guide before starting. Consult the live docs when an exact
API, option shape, or current product limit is uncertain. If network access is
unavailable, continue from installed types and bundled references and say what
could not be verified.

## Implementation rules

- If Fillo is absent, install the framework package with the host package
  manager and an explicit current

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.