@evanion/react-widget

Render a region of React components from structured data — a shop page, a back-office view, a configurable shelf — with the data checked against the components at compile time. Baize’s shelf below is two widget types and the items the shop’s data gives them.

import { createWidgets } from '@evanion/react-widget';
 
const ListingCard = ({ title, price }: { title: string; price: number }) => (
  <article className="listing">
    <h3>{title}</h3>
    <p>{price} kr</p>
  </article>
);
 
const TableBooking = ({
  tables,
  tonight,
}: {
  tables: number;
  tonight: boolean;
}) => (
  <div className="booking">
    <span>{tables} tables</span>
    <span>{tonight ? 'tonight' : 'this week'}</span>
  </div>
);
 
// Call once, at module scope.
const { Widgets, defineItems } = createWidgets({
  components: { listing: ListingCard, booking: TableBooking },
  chrome: {
    wrapper: ({ children }) => <section className="shelf">{children}</section>,
  },
});
 
export function Shelf() {
  return (
    <Widgets
      items={[
        { id: 'b1', type: 'booking', props: { tables: 4, tonight: true } },
        {
          id: 'g1',
          type: 'listing',
          props: { title: 'Brass: Birmingham', price: 649 },
        },
      ]}
    />
  );
}

The component map drives everything. An unknown type, a missing or mistyped prop, or children on a component that does not accept them is a compile error rather than a warning in a console somebody has to be watching.

Server components

The package carries no 'use client'. It uses only what React exports under the react-server condition — createElement, Suspense, memo — and no createContext, useContext, Component or stateful hook. A page that renders <Widgets> can be a Server Component, and a widget can be an async Server Component that fetches its own data.

There is no provider, no hook and no class error boundary here, because react/package.json maps the react-server condition to a build that does not export the APIs those need. What would have been context is a prop: ctx for page-level data, meta for placement.

What it gives you

Where to go next

• Getting started — install, the component map, typing items
• API reference — every export, every prop, every type
• Chrome, meta and Suspense — the composition seams
• Examples — worked regions
• Playground — run it in the browser
• Migrating from 0.1.x — the RSC redesign

Related packages

@evanion/astro-widget is the same idea for Astro: a registry instead of a component map, ctx instead of a provider, and no recursion into children because an Astro component receives child content through <slot />.

@evanion/compose handles the neighbouring problem of nesting providers, for the parts of an app that do have context.