Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

chore(claude): add react-hook-form skill (#48431)

Alaister Youngd845768fcf74
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 3cabdcbc36c..8f48264e86e 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -62,6 +62,7 @@ The skills in `.claude/skills/` are the source of truth for conventions — load
- `telemetry-standards` — PostHog events, `packages/common/telemetry-constants.ts`
- `dev-toolbar-review` — `packages/dev-tools`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`
- `safe-sql-execution` — any code that builds or executes SQL against user databases
+- `react-hook-form` — writing or modifying any form code, anywhere in the monorepo
- `vitest` / `vercel-composition-patterns` — generic unit-testing and React composition references
## Studio
diff --git a/.claude/skills/react-hook-form/SKILL.md b/.claude/skills/react-hook-form/SKILL.md
new file mode 100644
index 00000000000..ab1c39b05fe
--- /dev/null
+++ b/.claude/skills/react-hook-form/SKILL.md
@@ -0,0 +1,260 @@
+---
+name: react-hook-form
+description: Correct React Hook Form usage anywhere in the monorepo — data flow, subscriptions,
+ reset, dirty state, number inputs, and controlled-input rules. Load this BEFORE
+ writing or modifying ANY form code, adding a field to an existing form, touching
+ watch/useWatch/formState/getValues/setValue/reset, wiring a form into a dialog or
+ sheet, or building a submit/cancel footer — even when the change looks trivial.
+ The codebase contains widespread RHF anti-patterns; without this skill you will
+ copy them. For form layout and which components to use, also load
+ studio-ui-patterns.
+---
+
+# React Hook Form
+
+How to write forms that stay correct as they grow. The existing codebase is **not**
+a safe reference: `form.watch()` off prop-drilled form objects, subscription-only
+watches, unguarded `valueAsNumber`, and `?? undefined` controlled values are all
+common in older code and all wrong. Follow this skill, not the neighboring file.
+
+**Policy — fix what you touch.** New code must follow these rules. When you modify
+existing form code, upgrade the specific fields/hooks/components you're editing to
+match (e.g. a component you touch that calls `form.watch` gets converted to
+`useWatch`). Leave untouched code alone, but tell the user about anti-patterns you
+noticed and didn't fix. Never add new violations: `react-hook-form/no-use-watch`
+is ratcheted in Studio CI — any increase in the warning count fails the build.
+
+## Mental model: subscriptions decide who re-renders
+
+RHF is uncontrolled at heart. Values live in refs; nothing re-renders unless a
+subscription says so. Every read API is a subscription decision:
+
+| API | Subscribes | Re-renders | Use for |
+| ----------------------------- | ---------- | -------------------------- | ---------------------------------------------- |
+| `useWatch({ control, name })` | yes | only the calling component | reactive value reads, anywhere |
+| `useFormState({ control })` | yes | only the calling component | `isDirty`/`errors`/etc. outside the form owner |
+| `formState` (destructured) | yes | the `useForm` owner | form state **in the owner component only** |
+| `form.watch(name)` | yes | the **entire form tree** | avoid — lint-flagged, see below |
+| `getValues()` | no | never | event handlers and `onSubmit` only |
+| `subscribe()` | callback | none | side effects outside render |
+
+Two facts explain most of the bugs we've shipped:
+
+1. **`form.watch()` and `form.formState` hoist their subscription to the `useForm`
+ owner**, no matter which component calls them. A child that reads
+ `form.watch('x')` off a prop works today only because the whole tree re-renders
+ on every change — it silently goes stale the moment anyone adds `React.memo`
+ between owner and child, and until then it re-renders every sibling on every
+ keystroke. A no-arg `form.watch()` sets `watchAll` and re-renders the tree on
+ every field change for the life of the form.
+2. **`formState` is a Proxy** — reading a property is what arms the subscription.
+ Destructure it (`const { isDirty } = form.formState`), never pass the object
+ around or read it conditionally (`a && formState.isValid` may never subscribe).
+ Enforced by `react-hook-form/destructuring-formstate` (error).
+
+### Reading values, by location
+
+- **In the component that owns `useForm`:** destructure `formState`; prefer
+ `useWatch` over `form.watch` even here (the `no-use-watch` rule flags every
+ `watch`, and `useWatch` scopes the re-render if the JSX is later extracted).
+- **In any child component or custom hook:** accept `control` (not the whole
+ `form`) and use `useWatch({ control, name })` / `useFormState({ control })`.
+ Inside `<Form {...form}>` (which _is_ `FormProvider`), `useFormContext()` +
+ `useWatch({ name })` also works and avoids prop-drilling entirely.
+- **Consume the return value.** Never call a watch for its subscription side
+ effect and then read via `getValues()` — the watch list and the read list will
+ drift apart (it has already happened; fields silently lost reactivity). The
+ value you render must _be_ the value you subscribed to.
+- **One read path per value per render.** Mixing `useWatch('x')` on one line and
+ `getValues('x')` a few lines later lets the two disagree within a single render.
+- **Name what you watch.** `useWatch({ control })` with no `name` re-renders on
+ every keystroke in every field. Subscribe to the specific names you use.
+- `watch(callback)` is deprecated — use `subscribe()` for render-free listeners,
+ and always return its cleanup from `useEffect`.
+
+```tsx
+// ❌ common in the codebase — all three subscriptions hoist to the form owner
+function Fields({ form }: { form: UseFormReturn<FormValues> }) {
+ form.watch(['storageType', 'totalSize']) // return value discarded
+ const { errors } = form.formState // prop-form formState
+ const size = form.getValues('totalSize') // non-reactive read in render
+ ...
+}
+
+// ✅ child subscribes for itself and consumes what it watches
+function Fields({ control }: { control: Control<FormValues> }) {
+ const [storageType, totalSize] = useWatch({ control, name: ['storageType', 'totalSize'] })
+ const { errors } = useFormState({ control })
+ ...
+}
+```
+
+## The canonical form
+
+zod schema → `z.infer` type → `useForm` with `zodResolver` and **complete**
+`defaultValues` → `<Form {...form}>` → `FormField` render-prop per field →
+`FormItemLayout` → `FormControl` → primitive from `ui`. Layout/container choices
+(Card vs Sheet, `layout=` variants) are covered by the `studio-ui-patterns` skill
+and the demos in `apps/design-system/registry/default/example/`
+(`form-patterns-pagelayout.tsx`, `form-patterns-sidepanel.tsx`) — check them
+before inventing structure.
+
+```tsx
+const FormSchema = z.object({
+ name: z.string().min(1, 'Name is required'),
+ maxConnections: z
+ .union([z.literal(''), z.coerce.number().gte(1, 'Must be at least 1')])
+ .refine((v) => v !== '', 'Max connections is required'),
+})
+type FormValues = z.infer<typeof FormSchema>
+
+const form = useForm<FormValues>({
+ resolver: zodResolver(FormSchema),
+ defaultValues: { name: '', maxConnections: '' },
+})
+
+<Form {...form}>
+ <form id={formId} onSubmit={form.handleSubmit(onSubmit)}>
+ <FormField
+ control={form.control}
+ name="name"
+ render={({ field }) => (
+ <FormItemLayout layout="horizontal" label="Name">
+ <FormControl>
+ <Input {...field} />
+ </FormControl>
+ </FormItemLayout>
+ )}
+ />
+ </form>
+</Form>
+```
+
+Submit buttons living outside the `<form>` (sheet/dialog footers) use a stable
+`formId` and `form={formId}` on the button.
+
+## defaultValues, server data, and reset
+
+- **Provide a complete `defaultValues` object — every field, no `undefined`.**
+ `isDirty`, `dirtyFields`, and Cancel-reset all compare against it; a missing or
+ `undefined` default breaks all three, and `undefined` also makes React treat the
+ input as uncontrolled (see below).
+- **Form populated from an API? Use the `values` option, not a hand-rolled
+ effect.** `values` reacts to the query resolving and resets the form for you;
+ computing `defaultValues` from a query that may not have loaded freezes whatever
+ happened to be in cache at mount. Add
+ `resetOptions: { keepDirtyValues: true }` when a background refetch must not
+ clobber the user's in-progress edits. (Good examples:
+ `components/interfaces/Settings/Database/ConnectionLogging.tsx`,
+ `components/interfaces/Storage/EditBucketModal.tsx`.)
+- **After a successful mutation, re-baseline the form** in `onSuccess` so the
+ saved state becomes the new baseline (`isDirty` returns to false, Cancel now
+ reverts to the saved values). Prefer what the server actually persisted: if the
+ form uses `values` and the mutation invalidates the query, the refetch handles
+ this for you; if the mutation returns the updated resource, `reset(response)`.
+ `reset(submittedValues)` is the fallback for APIs that store exactly what was
+ sent — if the server normalizes or fills values, it baselines the form to data
+ that was never saved. A bare `reset()` reverts to the _previous_ defaults —
+ wrong after a save.
+- Cancel buttons call `form.reset()`. This only visually restores fields whose
+ values round-trip through defined, controlled values — which is why the null
+ rules below matter.
+
+## Controlled inputs: never let `value` flip to `undefined`
+
+React decides controlled vs uncontrolled per render from whether `value` is
+defined. A field whose value can be `undefined` (or becomes `undefined` on reset)
+flips modes: console warnings, and — worse — `reset()` stops clearing the visible
+text because React abandoned the DOM value. `value={field.value ?? undefined}` is
+a bug, not a fix.
+
+- Text fields: default to `''`, never `null`/`undefined`.
+- **Normalize `null` from the API at the form boundary** (`growthPercent ?? ''`
+ when building defaults) and convert back on submit (`'' → null`). Do not paper
+ over a `null` default with a `placeholder` that looks like a value: the user
+ sees "50", the form holds `null`, and every downstream comparison
+ (`defaultValues.growthPercent !== watched` → `null !== 50`) reports a permanent
+ phantom change while Cancel silently fails to reset the field.
+- Selects/radios: default to `''` or a real option value; checkboxes/switches to
+ `false`.
+
+## Number inputs
+
+The blessed pattern keeps `''` as the "empty" sentinel so the input stays
+controlled, and lets zod coerce on validation (see `maxConnections` above):
+`z.union([z.literal(''), z.coerce.number()...]).refine((v) => v !== '', '…')`
+with a plain `<Input {...field} type="number" />`.
+
+If you instead wire `onChange` through `e.target.valueAsNumber` (or
+`valueAsNumber: true`), an empty or partially-typed input produces `NaN`, which
+lands in form state and propagates into every calculation, price preview, and
+`value` attribute downstream. Guard it with the **same empty sentinel the
+field's schema declares** — with the `''`-union schema above:
+`field.onChange(Number.isNaN(e.target.valueAsNumber) ? '' : e.target.valueAsNumber)`.
+Never let `NaN` into form state.
+
+A nullable API field (`null` = "unset", e.g. a platform default applies)
+doesn't change the in-form sentinel — keep `''` inside the form and convert at
+the boundaries:
+
+```tsx
+// inbound: null → '' when building defaults/values
+values: { growthPercent: data.growth_percent ?? '' },
+// schema: '' stays the in-form sentinel, zod coerces real input
+growthPercent: z.union([z.literal(''), z.coerce.number().gte(10).lte(100)]),
+// outbound: '' → null in onSubmit
+mutate({ growth_percent: values.growthPercent === '' ? null : values.growthPercent })
+```
+
+If `null` does end up in form state (some existing forms hold it), keep it out
+of both the input and the coercion: render via `value={field.value ?? ''}`, and
+don't pass the value through `z.coerce.number()` — `Number(null)` is `0`, so a
+nullable field fed into the coercing union silently validates empty as `0`.
+Either way it's one sentinel per field, used consistently across defaults,
+schema, `onChange`, rendering, and the submit mapping.
+
+## Dirty state and change detection
+
+- Gate Save on `isDirty`; show Cancel only when dirty. In the owner, destructure
+ from `form.formState`; anywhere else, `useFormState({ control })`.
+- To show _which_ fields changed (review/summary dialogs), read `dirtyFields`
+ from the same subscription instead of hand-comparing
+ `defaultValues.x !== watchedX`. RHF already does that comparison correctly;
+ hand-rolled versions break on the null-vs-placeholder mismatch and must be
+ kept in sync with the watch list by hand.
+- `setValue` outside user input needs explicit flags:
+ `setValue('x', v, { shouldDirty: true, shouldValidate: true })` — otherwise the
+ change is invisible to `isDirty` and validation.
+
+## Disabling and gating
+
+If a field must not be edited (plan tier, permissions, cooldown), disable the
+field itself — a notice next to an editable input gates nothing. Wire the same
+condition into both the notice and the control. Permission checks come from
+`useAsyncCheckPermissions`; disabled buttons that need an explanation use
+`ButtonTooltip`.
+
+Caution: `register`/`useController` `disabled: true` removes the field's value
+from submission data. For "visible but locked" fields whose value must survive
+submit, use the input's own `disabled`/`readOnly` prop (as `FormField` +
+primitive props do) rather than RHF-level disabling, or the form-level
+`disabled` option to freeze everything during async work.
+
+## Submit and mutations
+
+`onSubmit` receives validated, typed data — trust it; don't re-read via
+`getValues()`. Mutations follow Studio conventions: `onSuccess` → `toast.success`
+
+- `reset(values)` (or query invalidation when using `values:`), `onError` →
+ `toast.error`; pass the mutation's `isPending` to the button's `loading` prop.
+ Default validation `mode: 'onSubmit'` is right for most forms — pick another mode
+ deliberately, not by copying.
+
+## Lint rules in force (Studio)
+
+| Rule | Level | Meaning |
+| ------------------------------------------- | ---------------- | ------------------------------------------------ |
+| `react-hook-form/destructuring-formstate` | error | destructure `formState`, never hold the object |
+| `react-hook-form/no-access-control` | error | don't reach into `control` internals |
+| `react-hook-form/no-nested-object-setvalue` | error | `setValue('a.b', v)`, not `setValue('a', {b:v})` |
+| `react-hook-form/no-use-watch` | warn (ratcheted) | use `useWatch`, not `watch` |
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index 502aa46c4b9..33ffc26b371 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -82,7 +82,7 @@ knowledge_base:
code_guidelines:
filePatterns:
# Studio code conventions — React/TS, UI patterns, composition, data fetching, errors
- - files: '.claude/skills/{studio-best-practices,studio-ui-patterns,vercel-composition-patterns,studio-queries,studio-error-handling}/SKILL.md'
+ - files: '.claude/skills/{studio-best-practices,studio-ui-patterns,vercel-composition-patterns,studio-queries,studio-error-handling,react-hook-form}/SKILL.md'
applyTo: 'apps/studio/**/*.{ts,tsx}'
# Studio unit / component test conventions
- files: '.claude/skills/{studio-testing,studio-mock-api-tests}/SKILL.md'
diff --git a/apps/studio/CLAUDE.md b/apps/studio/CLAUDE.md
index 53de52db891..5d4790ba751 100644
--- a/apps/studio/CLAUDE.md
+++ b/apps/studio/CLAUDE.md
@@ -6,17 +6,18 @@ Next.js pages router + TanStack Start (mid-migration, see below), React 19. Dev
Load the skills matching the task; stack them when a task spans areas:
-| Task | Additional skills |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
-| Query/mutation hooks, query keys (`data/**`) | `studio-queries` |
-| UI: pages, forms, tables, charts, sheets, empty states | `studio-ui-patterns` |
-| Displaying API errors | `studio-error-handling` |
-| Tests (deciding, writing, reviewing) | `studio-testing`, then `studio-mock-api-tests` (component/MSW) or `studio-e2e-tests` (Playwright) |
-| PostHog event tracking | `telemetry-standards` |
-| SQL against user databases | `safe-sql-execution` |
-| Logs Explorer SQL, `data/logs` | `clickhouse-logs-queries` |
-| Component API design, boolean-prop refactors | `vercel-composition-patterns` |
-| User-facing copy | `copywriting` |
+| Task | Additional skills |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Query/mutation hooks, query keys (`data/**`) | `studio-queries` |
+| UI: pages, forms, tables, charts, sheets, empty states | `studio-ui-patterns` |
+| Form logic: react-hook-form fields, watch/formState, reset, number inputs | `react-hook-form` |
+| Displaying API errors | `studio-error-handling` |
+| Tests (deciding, writing, reviewing) | `studio-testing`, then `studio-mock-api-tests` (component/MSW) or `studio-e2e-tests` (Playwright) |
+| PostHog event tracking | `telemetry-standards` |
+| SQL against user databases | `safe-sql-execution` |
+| Logs Explorer SQL, `data/logs` | `clickhouse-logs-queries` |
+| Component API design, boolean-prop refactors | `vercel-composition-patterns` |
+| User-facing copy | `copywriting` |
## TanStack Start migration