Recipes

Adding an option to an existing field

The smaller cousin of a new field type. For a field X in core/fields/x.ts:

1. Add the option to the field's configSchema (a z.strictObject), with a JSDoc comment and .describe().
2. Store it in the class constructor, and apply its default there (config.foo ?? default).
3. Use it in the right lifecycle method (prepareForSubmission for validation, exportForClient if the admin input needs it).
4. If it affects the column, update generateFieldSQL() (and the comparison logic in update-sections.ts) and schema-generator.ts.
5. Mirror client-side validation in src/validators/x.ts.
6. Tests: the field's unit tests, the validator's tests, and schema sync tests if the column changed.
7. Document it on the field's page in apps/docs/content/docs/fields/, with an example.
8. Add a changeset (minor).

Adding a section option

1. Add it to the section type's configSchema in core/sections/<type>.ts (or baseSectionOptionsSchema for all types).
2. Resolve it in the class constructor.
3. Consume it where it matters (page builders in api/actions/pages.ts, FieldFactory, submit, or schema sync).
4. Document it in the section's page and the options table on Sections.