@miniapp-studio/zapp-builder

@miniapp-studio/zapp-builder

How every @miniapp-studio/zapp component is edited in the builder: which properties each one offers, how they are grouped, and which input control each property gets.

This package exists because nothing else may hold both halves of that answer. zapp is a runtime package that a renderer route loads, so it must not know the editor's control vocabulary. builder is registry-agnostic — its shipped source knows no specific component — so it must not know zapp's components. This is the one place that knows both, and no renderer route imports it.

See package-boundaries.md for the dependency contract and the builder's property configuration for the vocabulary these files are written in.

Use

import { StudioBuilder } from "@miniapp-studio/builder";
import { createZappPropertiesRegistry } from "@miniapp-studio/zapp-builder";

const properties = createZappPropertiesRegistry();

<StudioBuilder registry={components} properties={properties} {...rest} />;

Create the registry once per host, like createZappRegistries. Every configuration is resolved against its component's Zod schema at creation, so a configuration that no longer fits its component throws immediately rather than producing a broken panel.

A host with its own component definitions registers their configurations alongside the built-ins:

const properties = createZappPropertiesRegistry({
  additionalConfigs: [[badgeDefinition, badgeConfig]],
});

What is here

src/components/ holds one file per group of components, plus shared-controls.ts for the choices and field groups more than one component declares — the flex-layout group, the alignment sets, and the font weights.

Each configuration is plain data. It names the properties the panel shows, in the order it shows them, and gives each one a control kind. It states no bounds: min, max, step, and string lengths are read from the component's Zod schema, so the two can never disagree.

Two things a configuration deliberately does not do

It does not list every property. The configuration is authoritative about what is editable. A property the schema describes but no group names is simply not shown — which is how a deliberately hidden property is expressed. The cost is that adding a property to a *.props.ts will not appear in the panel until someone adds it here, and no test reports that.

It does not edit arrays. zapp.StandardInput.options, zapp.ProductFilter.options, and zapp.ChoicePicker.options are z.array() of option objects, which no control in the closed set edits. They were never editable — the old panel discovered them as unsupported fields and rendered a note — so nothing regressed. A repeater control, or a custom one, is where they would be added.

Tests

src/configs.test.ts covers what a test can catch: that every component zapp registers by default has a configuration, that every configuration registers without throwing, and that the controls this package exists to fix — Button's fontWeight, align, and justify — are pickers rather than text boxes.

It cannot catch a property that gained a schema entry but no field. That is the accepted cost of the configuration being authoritative.