Migrate a React @tanstack/react-form codebase from the prop-drilled `useForm` + erased-form-type pattern to the official `createFormHook` composition API (`useAppForm` / `withForm` / `field.X`). Use when a project threads a `form` object (often cast to an `any`-erased type like `ReactFormExtendedApi<any,...>`) through field-wrapper components that take `form`+`name` props, and you want typed field names/values, no casts, and reusable bound field components. Triggers: "migrate forms to createFormHook", "adopt useAppForm/withForm", "remove AnyReactForm cast", "type-safe tanstack form fields".
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
tanstack-form-composition
description
Migrate a React @tanstack/react-form codebase from the prop-drilled `useForm` + erased-form-type pattern to the official `createFormHook` composition API (`useAppForm` / `withForm` / `field.X`). Use when a project threads a `form` object (often cast to an `any`-erased type like `ReactFormExtendedApi<any,...>`) through field-wrapper components that take `form`+`name` props, and you want typed field names/values, no casts, and reusable bound field components. Triggers: "migrate forms to createFormHook", "adopt useAppForm/withForm", "remove AnyReactForm cast", "type-safe tanstack form fields".
TanStack Form → composition API migration
Convert a React project using @tanstack/react-form from raw useForm +
prop-drilled field wrappers + an any-erased form type to the createFormHook
composition API. The payoff: typed field names/values, deletion of the erased
form type and every as unknown as <ErasedForm> cast, and bound field components
consumed as field.TextField instead of <FieldWrapper form={form} name=… />.
This is for the React adapter. Solid/Vue/Angular have the same API shape with
different hook names — the concepts below port directly.
When this applies
The codebase has most of these symptoms:
An erased form type alias, e.g. type AnyForm = ReactFormExtendedApi<any,any,…>
(12 any generics), used as a prop type and reached via form as unknown as AnyForm.
Field components that accept form + name props and internally render
<form.Field name={name}>…</form.Field>.
Shared "section" components that receive the whole form as a prop and are
reused across multiple parent forms (e.g. a settings form and an onboarding wizard).
Helper functions that take the form and call getFieldValue/setFieldValue.
If the project does not yet use @tanstack/react-form, stop — this skill
migrates an existing TanStack Form codebase; it does not introduce the library.
Method
Work in four phases. Do recon fully before editing; build the shared infra once;
then migrate call sites; then delete the erased type and verify. On a large repo,
migrate one simple form end-to-end first as a reference, then fan out.
Phase 0 — Recon
Confirm the version and map the blast radius. Run (adapt paths):
Dependency: grep package.json for @tanstack/react-form (need v1+; createFormHook,
createFormHookContexts, withForm are stable in v1).
Form-creation sites: search useForm(.
The erased type + casts: search the alias name and as unknown as.
Existing field wrappers: the directory of components taking form/name props.
Shared sections: components whose props include the erased form type.
Form-consuming helpers: functions whose parameter is the erased form type.
Record every hit; these are your edit targets. Note which field wrappers are
actually used (unused ones still get converted for library consistency, but have
no call sites to update).
Phase 1 — Build the composition infra (once per form tree)
Create these alongside the existing field components (e.g. components/ui/form/).
form-context.ts — shared contexts, isolated to avoid a circular import with
the hook:
error-message.ts — one extractor (field meta.errors may hold Zod issue
objects, strings, or thrown values):
exportfunctionfirstErrorMessage(errors: ReadonlyArray<unknown>): string | undefined {
const first = errors[0];
if (!first) returnundefined;
if (typeof first === "string") return first;
return (first as { message?: string }).message ?? String(first);
}
Bound field components — each reads useFieldContext<T>() instead of taking
form/name. useFieldContext<T>() is a local cast: it does not enforce that
T matches the actual field, so pick the widest value the component handles.
// thin wrapper over a presentational base componentexportfunctionTextField(props: TextFieldProps): ReactElement {
const field = useFieldContext<string | number | null | undefined>();
return (
<BaseTextFieldvalue={field.state.value ?? ""}
onChange={(e) => field.handleChange(/* coerce per type */ e.target.value)}
onBlur={field.handleBlur}
errorText={firstErrorMessage(field.state.meta.errors)}
{...props}
/>
);
}
Form-level SubmitButton — subscribes to submit state:
Keep type="submit" and let the enclosing <form onSubmit> drive submission;
expose disabled so callers fold in external state (e.g. a pending mutation that
the form's own isSubmitting doesn't observe).
index.ts — wire the hook. Name the bound components so the registry keys are
shorthand:
Form creation:useForm({ … }) → useAppForm({ … }). Same options object
(defaultValues, validators, onSubmit). Delete the const formApi = form as unknown as AnyForm line.
form.AppField type-checks name against the form's data shape and types
field.state.value / field.handleChange. One-off custom controls also work
inside AppField via field.state / field.handleChange (the field arg carries
both the API and the bound components).
Submit: wrap in form.AppForm and use form.SubmitButton where it fits
(simple dialogs). Forms with bespoke submit UX (steppers, mode-dependent labels)
keep a custom button but still benefit from the typed form.
Shared sections → withForm. This is usually the biggest cleanup: it removes
the erased-type threading while keeping types across the boundary.
exportconstPersonalSection = withForm({
defaultValues: DEFAULTS, // type-only; must match the parent form's data typeprops: { title: "" }, // optional extra props with defaultsrender: functionPersonalSection({ form, title }) {
return (
<form.AppFieldname="firstName">
{(field) => <field.TextFieldlabel="First name" />}
</form.AppField>
);
},
});
// consumed by the parent, passing its typed useAppForm instance:<PersonalSectionform={form}title="…" />;
defaultValues is for type inference only (not runtime). It must match the
consuming useAppForm's data type — reuse the project's shared DEFAULTS constant.
withForm calls render during its own component's render, so hooks inside
render are safe (state, queries, effects). Name the render function
PascalCase so lint treats it as a component.
A child that only reads state (a validation summary, a derived banner) is also a
clean withForm.
Helper functions that take the form: do not reintroduce any. Define a
minimal structural interface with the literal field-name union it touches — the
typed form is assignable to it:
Delete the erased form type file/alias; confirm zero references remain.
Optionally drop redundant prefixes on bound components (they're consumed as
field.TextField, so a Form prefix is noise) and rename files to match.
Run the project's typecheck, then lint, then formatter, and fix
fallout. The most common new errors are real bugs the any erasure hid —
especially number text fields whose handleChange(null)/Number(x) now meets a
typed field. Resolve by widening the bound component's useFieldContext union
(string | number | null | undefined) rather than re-adding any.
Key decisions & gotchas
Presentational base vs. thin wrapper — how deep? Two layers (a controlled,
form-agnostic base component + a thin context wrapper) is cleanest, and lets the
base be reused outside forms. But the base layer earns its keep mainly when the
UI library needs heavy per-instance wrapping (e.g. react-native-paper:
outline radii, helper-text layout, labeled rows). When components are already
"complete" and themed globally (e.g. MUI), a base for trivial controls
(checkbox/switch/toggle/select) is just indirection — split only the substantive
ones (text/currency/multiselect) and keep the rest as direct thin bindings.
Naming collisions. Bound components named TextField / Select / Switch
shadow the UI library's exports. Alias the import in that file
(import { TextField as MuiTextField } from "…", or the base as BaseTextField).
useFieldContext<T>() is a cast, not a constraint. It won't error if T
disagrees with the actual field; choose the widest value the component renders.
Don't force every form into SubmitButton. Steppers and multi-action footers
legitimately keep custom buttons; the typed form is the real win.
Migrate incrementally. The new infra can coexist with old prop-drilled
wrappers, so you can convert one form at a time and keep the project compiling.
Definition of done
Typecheck, lint, and formatter all pass; the erased form type is gone; every
useForm is now useAppForm; field components are consumed via form.AppField /
field.X; shared sections and form-consuming helpers are typed (via withForm and
structural accessors) with no any.
