migrate-frontend-forms

Form Migration Guide

This skill helps migrate forms from Sentry's legacy form system (JsonForm, FormModel) to the new TanStack-based system.

Feature Mapping

Old System New System Notes

saveOnBlur: true

AutoSaveField

Default behavior

confirm

confirm prop string | ((value) => string | undefined)

showHelpInTooltip

variant="compact"

On layout components

disabledReason

disabled="reason"

String shows tooltip

extraHelp

JSX in layout Render <Text> below field

getData

mutationFn

Transform data in mutation function

mapFormErrors

setFieldErrors

Transform API errors in catch block

saveMessage

onSuccess

Show toast in mutation onSuccess callback

formatMessageValue

onSuccess

Control toast content in onSuccess callback

resetOnError

onError

Call form.reset() in mutation onError

saveOnBlur: false

useScrapsForm

Use regular form with explicit Save button

help

hintText

On layout components

label

On layout components

required

On layout + Zod schema

Feature Details

confirm → confirm prop

Old:

{ name: 'require2FA', type: 'boolean', confirm: { true: 'Enable 2FA for all members?', false: 'Allow members without 2FA?', }, isDangerous: true, }

New:

<AutoSaveField name="require2FA" confirm={value => value ? 'Enable 2FA for all members?' : 'Allow members without 2FA?' } {...}

showHelpInTooltip → variant="compact"

Old:

{ name: 'field', help: 'This is help text', showHelpInTooltip: true, }

New:

<field.Layout.Row label="Field" hintText="This is help text" variant="compact"

disabledReason → disabled="reason"

Old:

{ name: 'field', disabled: true, disabledReason: 'Requires Business plan', }

New:

<field.Input disabled="Requires Business plan" {...} />

extraHelp → JSX

Old:

{ name: 'sensitiveFields', help: 'Main help text', extraHelp: 'Note: These fields apply org-wide', }

New:

<field.Layout.Stack label="Sensitive Fields" hintText="Main help text"> <field.TextArea {...} /> <Text size="sm" variant="muted"> Note: These fields apply org-wide </Text> </field.Layout.Stack>

getData → mutationFn

The getData function transformed field data before sending to the API. In the new system, handle this in the mutationFn .

Old:

// Wrap field value in 'options' key { name: 'sentry:csp_ignored_sources_defaults', type: 'boolean', getData: data => ({options: data}), }

// Or extract/transform specific fields { name: 'slug', getData: (data: {slug?: string}) => ({slug: data.slug}), }

New:

<AutoSaveField name="sentry:csp_ignored_sources_defaults" schema={schema} initialValue={project.options['sentry:csp_ignored_sources_defaults']} mutationOptions={{ mutationFn: data => { // Transform data before API call (equivalent to getData) const transformed = {options: data}; return fetchMutation({ url: /projects/${organization.slug}/${project.slug}/, method: 'PUT', data: transformed, }); }, }}

{field => ( <field.Layout.Row label="Use default ignored sources"> <field.Switch checked={field.state.value} onChange={field.handleChange} /> </field.Layout.Row> )} </AutoSaveField>

Simpler pattern - If you just need to wrap the value:

mutationOptions={{ mutationFn: fieldData => { return fetchMutation({ url: /projects/${org}/${project}/, method: 'PUT', data: {options: fieldData}, // getData equivalent }); }, }}

Important: Typing mutations correctly

The mutationFn should be typed with the API's data type (e.g., Partial<Organization> , Partial<Project> ), not the schema-inferred type. The schema is for client-side field validation only — the mutation receives whatever the API endpoint accepts. Tying the mutation to the schema couples two unrelated concerns and can cause type errors when the schema types don't exactly match the API types.

// ❌ Don't use generic types - breaks field type narrowing mutationOptions={{ mutationFn: (data: Record<string, unknown>) => { return fetchMutation({url: '/user/', method: 'PUT', data: {options: data}}); }, }}

// ❌ Don't tie mutation type to the zod schema mutationOptions={{ mutationFn: (data: Partial<z.infer<typeof preferencesSchema>>) => { return fetchMutation({url: '/user/', method: 'PUT', data: {options: data}}); }, }}

// ✅ Use the API's data type mutationOptions={{ mutationFn: (data: Partial<UserDetails>) => { return fetchMutation({url: '/user/', method: 'PUT', data: {options: data}}); }, }}

Make sure the zod schema's types are compatible with (i.e., assignable to) the API type. For example, if the API expects a string union like 'off' | 'low' | 'high' , use z.enum(['off', 'low', 'high']) instead of z.string() .

mapFormErrors → setFieldErrors

The mapFormErrors function transformed API error responses into field-specific errors. In the new system, handle this in the catch block using setFieldErrors .

Old:

// Form-level error transformer function mapMonitorFormErrors(responseJson?: any) { if (responseJson.config === undefined) { return responseJson; } // Flatten nested config errors to dot notation const {config, ...rest} = responseJson; const configErrors = Object.fromEntries( Object.entries(config).map(([key, value]) => [config.${key}, value]) ); return {...rest, ...configErrors}; }

New:

import {setFieldErrors} from '@sentry/scraps/form';

    for (const [key, value] of Object.entries(rest)) {
      errors[key] = {message: Array.isArray(value) ? value[0] : String(value)};
    }
    for (const [key, value] of Object.entries(config)) {
      errors[`config.${key}`] = {message: Array.isArray(value) ? value[0] : String(value)};
    }

    setFieldErrors(formApi, errors);
  }
}

}, });

Simpler pattern - For flat error responses:

onSubmit: async ({value, formApi}) => { try { await mutation.mutateAsync(value); } catch (error) { // API returns {email: ['Already taken'], username: ['Invalid']} const errors = error.responseJSON; if (errors) { setFieldErrors(formApi, { email: {message: errors.email?.[0]}, username: {message: errors.username?.[0]}, }); } } },

Note: setFieldErrors supports nested paths with dot notation: 'config.schedule': {message: 'Invalid schedule'}

saveMessage → onSuccess

The saveMessage showed a custom toast/alert after successful save. In the new system, handle this in the mutation's onSuccess callback.

Old:

{ name: 'fingerprintingRules', saveOnBlur: false, saveMessageAlertVariant: 'info', saveMessage: t('Changing fingerprint rules will apply to future events only.'), }

New:

import {addSuccessMessage} from 'sentry/actionCreators/indicator';

<AutoSaveField name="fingerprintingRules" schema={schema} initialValue={project.fingerprintingRules} mutationOptions={{ mutationFn: data => fetchMutation({...}), onSuccess: () => { // Custom success message (equivalent to saveMessage) addSuccessMessage(t('Changing fingerprint rules will apply to future events only.')); }, }}

formatMessageValue → onSuccess

The formatMessageValue controlled how the changed value appeared in success toasts. Setting it to false disabled showing the value entirely (useful for large text fields). In the new system, you control this directly in onSuccess .

Old:

{ name: 'fingerprintingRules', saveMessage: t('Rules updated'), formatMessageValue: false, // Don't show the (potentially huge) value in toast }

New:

mutationOptions={{ mutationFn: data => fetchMutation({...}), onSuccess: () => { // Just show the message, no value (equivalent to formatMessageValue: false) addSuccessMessage(t('Rules updated')); }, }}

// Or if you want to show a formatted value: onSuccess: (data) => { addSuccessMessage(t('Slug changed to %s', data.slug)); },

resetOnError → onError

The resetOnError option reverted fields to their previous value when a save failed. In the new system, call form.reset() in the mutation's onError callback.

Old:

// Form-level reset on error <Form resetOnError apiEndpoint="/auth/" {...}>

// Or field-level (BooleanField always resets on error) <FormField resetOnError name="enabled" {...}>

New (with useScrapsForm):

New (with AutoSaveField):

<AutoSaveField name="enabled" schema={schema} initialValue={settings.enabled} mutationOptions={{ mutationFn: data => fetchMutation({...}), onError: () => { // The field automatically shows error state via TanStack Query // If you need to reset the value, you can pass a reset callback }, }}

Note: AutoSaveField with TanStack Query already handles error states gracefully - the mutation's isError state is reflected in the UI. Manual reset is typically only needed for specific UX requirements like password fields.

saveOnBlur: false → useScrapsForm

Fields with saveOnBlur: false showed an inline alert with Save/Cancel buttons instead of auto-saving. This was used for dangerous operations (slug changes) or large text edits (fingerprint rules).

In the new system, use a regular form with useScrapsForm and an explicit Save button. This preserves the UX of showing warnings before committing.

Old:

{ name: 'slug', type: 'string', saveOnBlur: false, saveMessageAlertVariant: 'warning', saveMessage: t("Changing a project's slug can break your build scripts!"), }

New:

import {Alert} from '@sentry/scraps/alert'; import {Button} from '@sentry/scraps/button'; import {defaultFormOptions, useScrapsForm} from '@sentry/scraps/form';

const slugSchema = z.object({ slug: z.string().min(1, 'Slug is required'), });

function SlugForm({project}: {project: Project}) { const mutation = useMutation({ mutationFn: (data: {slug: string}) => fetchMutation({url: /projects/${org}/${project.slug}/, method: 'PUT', data}), });

const form = useScrapsForm({ ...defaultFormOptions, defaultValues: {slug: project.slug}, validators: {onDynamic: slugSchema}, onSubmit: ({value}) => mutation.mutateAsync(value).catch(() => {}), });

return ( <form.AppForm form={form}> <form.AppField name="slug"> {field => ( <field.Layout.Stack label="Project Slug"> <field.Input value={field.state.value} onChange={field.handleChange} /> </field.Layout.Stack> )} </form.AppField>

  {/* Warning shown before saving (equivalent to saveMessage) */}
  &#x3C;Alert variant="warning">
    {t("Changing a project's slug can break your build scripts!")}
  &#x3C;/Alert>

  &#x3C;Flex gap="sm" justify="end">
    &#x3C;Button onClick={() => form.reset()}>Cancel&#x3C;/Button>
    &#x3C;form.SubmitButton>Save&#x3C;/form.SubmitButton>
  &#x3C;/Flex>
&#x3C;/form.AppForm>

); }

When to use this pattern:

Dangerous operations where users should see a warning before committing (slug changes, security tokens)
Large multiline text fields where you want to finish editing before saving (fingerprint rules, filters)
Any field where auto-save doesn't make sense

Preserving Form Search Functionality

Sentry's SettingsSearch allows users to search for individual settings fields. When migrating forms, you must preserve this searchability by wrapping migrated forms with FormSearch .

The FormSearch Component

FormSearch is a build-time marker component — it has zero runtime behavior and simply renders its children unchanged. Its route prop is read by a static extraction script to associate form fields with their navigation route, enabling them to appear in SettingsSearch results.

import {FormSearch} from 'sentry/components/core/form';

<FormSearch route="/settings/account/details/"> <FieldGroup title={t('Account Details')}> <AutoSaveField name="name" schema={schema} initialValue={user.name} mutationOptions={...}> {field => ( <field.Layout.Row label={t('Name')} hintText={t('Your full name')} required> <field.Input /> </field.Layout.Row> )} </AutoSaveField> </FieldGroup> </FormSearch>

Props:

Prop Type Description

route

string

The settings route for this form (e.g., '/settings/account/details/' ). Used for search navigation.

children

ReactNode

The form content — rendered unchanged at runtime.

Rules:

The route must match the settings page URL exactly (including trailing slash).
Wrap the entire form section with a single FormSearch , not individual fields.
Every <AutoSaveField> or <form.AppField> inside a FormSearch will be indexed. Make sure label and hintText are plain string literals or t() calls — computed/dynamic strings will be skipped by the extractor.

The Form Field Registry

After adding or updating FormSearch wrappers, regenerate the field registry so that search results stay up to date:

pnpm run extract-form-fields

This script (scripts/extractFormFields.ts ) scans all TSX files, finds <FormSearch> components, extracts field metadata (name , label , hintText , route ), and writes the generated registry to static/app/components/core/form/generatedFieldRegistry.ts . Commit this generated file alongside your migration PR — it is part of the source tree.

Run the command after any change to forms inside a FormSearch wrapper (adds, removals, label changes). The generated file is checked in and should not be edited manually.

Migration: Old Forms Already Searchable

If the legacy JsonForm being migrated was already indexed by SettingsSearch (i.e., it had entries in sentry/data/forms ), you must add a FormSearch wrapper to the new form so search functionality is preserved. The old and new sources coexist — new registry entries take precedence over old ones for the same route + field combination — but once you remove the legacy form the old entries will disappear.

Handling Nullable Initial Values

Legacy select fields often started with an empty/undefined value and required a selection. In the new system, use .nullable().refine() in the schema, type defaultValues with z.input<typeof schema> , and call schema.parse(value) in onSubmit .

Old:

{ name: 'provider', type: 'select', required: true, choices: [['github', 'GitHub'], ['launchdarkly', 'LaunchDarkly']], }

New:

const schema = z.object({ provider: z .enum(['github', 'launchdarkly']) .nullable() .refine(v => v !== null, 'Provider is required'), });

// z.input accepts null; z.output (after refine) does not const defaultValues: z.input<typeof schema> = { provider: null, };

const form = useScrapsForm({ ...defaultFormOptions, defaultValues, validators: {onDynamic: schema}, onSubmit: ({value}) => { // schema.parse narrows null away — mutation receives z.output return mutation.mutateAsync(schema.parse(value)).catch(() => {}); }, });

This pattern is necessary whenever a required field has no meaningful initial value. The z.input / z.output distinction ensures the form accepts null as default while the mutation receives the validated, non-null type.

Intentionally Not Migrated

Feature Usage Reason

allowUndo

3 forms Undo in toasts adds complexity with minimal benefit. Use simple error toasts instead.

Migration Checklist

Replace JsonForm/FormModel with useScrapsForm or AutoSaveField
Convert field config objects to JSX AppField components
Replace help → hintText on layouts
Replace showHelpInTooltip → variant="compact"
Replace disabledReason → disabled="reason string"
Replace extraHelp → additional JSX in layout
Convert confirm object to function: (value) => message | undefined
Handle getData in mutationFn
Handle mapFormErrors with setFieldErrors in catch
Handle saveMessage in onSuccess callback
Convert saveOnBlur: false fields to regular forms with Save button
Verify onSuccess cache updates merge with existing data (use updater function) — some API endpoints may return partial objects
Wrap the migrated form with <FormSearch route="..."> if the old form was searchable in SettingsSearch
Run pnpm run extract-form-fields and commit the updated generatedFieldRegistry.ts

migrate-frontend-forms

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

design-system

generate-migration

warden

generate-frontend-forms