Build an app for SeraFox

Apps are small features merchants install from the App Store. Each app has a definition (name, description, settings form) and code that runs on the storefront. The merchant gets an install button, an auto-generated settings form and an on/off switch for free.

1. Define the app

Add an entry to src/lib/apps/registry.ts. The fields list becomes the settings form and is validated on the server.

{
  key: "back-in-stock", name: "Back in stock", category: "Marketing", developer: "You",
  icon: "EnvelopeSimple", color: "#7c3aed", tagline: "…", description: "…", features: ["…"],
  defaults: { message: "Notify me" },
  fields: [{ key: "message", label: "Button text", type: "text" }],
}

2. Render it on the storefront

In src/components/storefront/apps.tsx, read the merchant's settings with useApp("your-key") — it returns null when the app isn't installed or is off — and render your component. Floating widgets go in AppsHost; banners, cart widgets and footer items have their own spots in the theme frame.

function BackInStock() {
  const cfg = useApp("back-in-stock");
  if (!cfg) return null;
  return <button>{String(cfg.message)}</button>;
}

3. Need server logic?

Add a server action beside the storefront actions (src/app/s/[slug]/actions.ts). Scope every query by the store id and validate input with zod, as the email popup does.

Quick option: custom code

Any merchant can already install Custom code and paste a script tag — useful for connecting an existing widget before you turn it into a full app.

The full guide, including testing and publishing tips, is in docs/APPS.md in the repository.