Widget

A widget is an on-page component that the people building Vincia sites can drop onto a page or dashboard. It runs in a sandbox: you get your own storage namespace and your own list of outbound URLs you're allowed to call. You also expose a typed config schema so the page editor can offer the right knobs.

Ship four visual states — empty, loading, error, populated — so the widget looks right in every situation.

A minimal widget

import { defineWidget } from '@vincia/sdk/widget';
import { useStorage } from '@vincia/sdk/widget/hooks';

export default defineWidget({
  id: 'hello-widget',
  version: '0.1.0',
  config: {
    greeting: { type: 'string', default: 'Hello' },
  },
  Component({ config }) {
    const [name] = useStorage<string>('display_name');
    return <p>{config.greeting}, {name ?? 'world'}!</p>;
  },
});

What you get on ctx

• useStorage(key) — per-build scoped storage
• useOutbound(host) — scoped outbound fetch with caps enforced
• useSecrets() — read scoped, never written from widget code

See the API reference for the full hook surface.

What gets reviewed

• React component returns a valid tree (no manual DOM mutation)
• Storage keys are scoped (no cross-tenant reads)
• Outbound caps are honored
• Config schema is well-formed and accept-kinds declared