SDK extensions

Add server behavior and keep field conversion explicit.

A BacklitExtension is a function that registers server behavior and returns { name, version }. Import the type from @backlit/sdk/types. Pass extension functions to defineApp({ extensions, areas }).

An app runs each function identity once. A second app can run the same function again. Registries and factory macros are process-wide, so extension changes affect all apps in that process. Later registrations replace earlier ones. Two functions with the same extension name both run and produce a warning.

Factories and macros

FieldsFactory, FiltersFactory, WidgetsFactory, and ChartsFactory extend Macroable. Use their static macro API to add factory methods. Declare the new method through TypeScript module augmentation. Extend the matching open protocol registry in @backlit/contract, then install a matching client renderer. Runtime registration and type augmentation are both required.

Remappers

remappers is the process-wide FieldRemappers instance. Use registerRole(role, map) for a complete role map. Use registerRemappers(role, partialMap) to replace entries in an existing role. Registering replacements for an unknown role throws.

A FieldRemapper receives (value, field, record, parent, report). Return the converted value. Call report(reason) when conversion fails. The returned undefined causes the value to be omitted. Preserve null when it is a valid empty value. The remapper converts data; the client formats its display.

Built-in maps cover text, number, boolean, date, enum, and group fields for display and input. Relation builders handle related records themselves. A missing role handler reports a defect and uses the requested fallback role. A missing fallback handler throws E_MISSING_FIELD_REMAPPER.

Defect reporters

Use .onDefect(reporter) on a data block or form. A defect has a reason and can include field, kind, value, and row index. The default warnOnDefect writes a warning. A custom reporter can throw new Error(defect.reason) to stop on invalid data during development.

An invalid declaration, duplicate name, missing required position, or invalid target argument is an authoring error. These errors throw. A failed data conversion is a defect. The block can keep its other valid values.

Builder contracts

Import TO_NODE, RESOLVE, RESOLVE_FOR, TO_RESPONSE, FIELD_NAME, FIELD_VALUE, FIELD_ROW, VALUE_FOR, KEYWORD, and PARSE from @backlit/sdk/symbols. Import contract types from @backlit/sdk/types. Nodeable creates a node synchronously. Resolvable creates it asynchronously and can locate a zone. Respondable creates a response. Field builders carry their field name and value type and convert record values through VALUE_FOR.

The generated SDK API, types, and symbols include all exported declarations and helper functions. Prefer public factories when you author an application. See Field roles for a complete custom role.