Add a settings panel

A settings panel is the one form owners see for your extension, on the install’s page in their dashboard. Its values persist as a reserved storage document and reach your server as documents.settings on every call.

tappify extension add settings

The manifest entry

{
  "contributes": {
    "settings": {
      "entry": "src/settings.tsx",
      "schema": { "$ref": "./schemas/settings.json" }
    }
  }
}

The command writes this entry. You can hand-edit tappify.extension.json instead — the $schema line gives your editor completion and validation, and tappify extension doctor checks the result. The command also writes schemas/settings.json with a single enabled boolean in it, there to be replaced by what owners set. The examples on this page are written against two properties:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Settings",
  "type": "object",
  "properties": {
    "refreshMinutes": {
      "type": "number",
      "title": "Refresh minutes",
      "description": "How often the summary asks the server for new numbers"
    },
    "showDelta": {
      "type": "boolean",
      "title": "Show change",
      "description": "Show the change against the previous period"
    }
  },
  "required": ["refreshMinutes"],
  "additionalProperties": false
}

Run tappify extension types after every edit to the schema, so the generated TapSettings follows it.

The component

TapSettingsProps gives you the current values and one callback. Render the schema with TapForm rather than writing inputs by hand — it maps the same schema the manifest points at, so the form and the generated TapSettings type cannot disagree.

import {
  TapForm,
  TapPageHeader,
  type TapSettingsProps,
} from "@tappify/extension-sdk";
import "@tappify/extension-sdk/styles.css";
import schema from "../schemas/settings.json";

export default function Settings({ values, onChange }: TapSettingsProps) {
  return (
    <div className="tap-stack">
      <TapPageHeader
        title="Settings"
        description="These values reach your server as documents.settings on every call."
      />
      <TapForm
        schema={schema}
        value={values}
        submitLabel="Save"
        onSubmit={(next) => onChange(next)}
      />
    </div>
  );
}

Where the values go

Saving writes the install-scoped settings singleton, which is why storage may not declare a collection of that name. Three things happen at once:

The document is validated against your schema before it is stored.
Every mount of your extension in that browser is told, so a widget reflects a saved preference without a reload.
A settings.changed event fires, which your UI can subscribe to and your server can receive.

Your server sees the current values as documents.settings on every call it receives, so it never asks Tappify for them.

procedures: {
  getSummary: (request) => {
    const minutes = request.documents.settings?.refreshMinutes ?? 15;
    return { installs: 0, delta: 0, refreshedEvery: minutes };
  },
},

Build forms from schemas

What TapForm renders for each schema construct.

Store data with hosted storage

Collections of your own, scoped per teammate, install or workspace.

Preview in the portal

Render the panel against fixture data before anything is installed.

Start

Build

Test

Publish

Reference

The manifest entry

The component

Where the values go

Build forms from schemas

Store data with hosted storage

Preview in the portal

​The manifest entry

​The component

​Where the values go

Build forms from schemas

Store data with hosted storage

Preview in the portal

The manifest entry

The component

Where the values go