migrate-frontend-forms

仓库: getsentry/sentry
安装量: 48
排名: #15540

安装

npx skills add https://github.com/getsentry/sentry --skill 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
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
label
On layout components
required
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
,
Partial
),
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
}
;
}
<
Form
mapFormErrors
=
{
mapMonitorFormErrors
}
{
...
}
>
New:
import
{
setFieldErrors
}
from
'@sentry/scraps/form'
;
const
form
=
useScrapsForm
(
{
...
defaultFormOptions
,
defaultValues
:
{
...
}
,
validators
:
{
onDynamic
:
schema
}
,
onSubmit
:
async
(
{
value
,
formApi
}
)
=>
{
try
{
await
mutation
.
mutateAsync
(
value
)
;
}
catch
(
error
)
{
// Transform API errors and set on fields (equivalent to mapFormErrors)
const
responseJson
=
error
.
responseJSON
;
if
(
responseJson
?.
config
)
{
// Flatten nested errors to dot notation
const
{
config
,
...
rest
}
=
responseJson
;
const
errors
:
Record
<
string
,
{
message
:
string
}
>
=
{
}
;
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
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':
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):
const
form
=
useScrapsForm
(
{
...
defaultFormOptions
,
defaultValues
:
{
password
:
''
}
,
validators
:
{
onDynamic
:
schema
}
,
onSubmit
:
async
(
{
value
}
)
=>
{
try
{
await
mutation
.
mutateAsync
(
value
)
;
}
catch
(
error
)
{
// Reset form to previous values on error (equivalent to resetOnError)
form
.
reset
(
)
;
throw
error
;
// Re-throw if you want error handling to continue
}
}
,
}
)
;
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) / } < Alert variant = " warning "

{ t ( "Changing a project's slug can break your build scripts!" ) } </ Alert

< Flex gap = " sm " justify = " end "

< Button onClick = { ( ) => form . reset ( ) }

Cancel </ Button

< form.SubmitButton

Save </ form.SubmitButton

</ Flex

</ 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 or 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 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. 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 if the old form was searchable in SettingsSearch Run pnpm run extract-form-fields and commit the updated generatedFieldRegistry.ts

← 返回排行榜