60.537° N 5.269° E

Turlogg · Trail log

Vercel's ui-sdk Runs on Preact

Vercel's ui-sdk ships adapters for React, Vue, Svelte, Solid and web components. Its React adapter also runs on Preact 11 through preact/compat, Preact's React compatibility layer, with a small module of fixes and no changes to its code. All 55 components now ship inside the developing-preact skill as plain JavaScript files. A page that uses them is an HTML file and a folder of scripts: no TypeScript, no npm install, no bundler and no build step, so an agent can write it and publish it to any static host, such as GitHub Pages, as it is. Every upstream example runs on a showcase page under AI Tools.

The ui-sdk on Preact showcase: a menubar and component sidebar, with a Menu example open on the right.
The showcase. The menubar, the search button and the open menu are ui-sdk components rendered by Preact.

ui-sdk is the behavior layer under a component library

ui-sdk is a TypeScript library of unstyled UI behaviors: keyboard navigation, focus, selection, dismissal, popups and the ARIA each needs, assembled into 55 components such as Dialog, Menu, Combobox, Tabs and Date Picker. It is Apache-2.0 and in beta. Used as its docs describe, it means TypeScript, npm packages and a bundler such as Vite.

On November 18 Oskar linked its docs and asked: "Could we build a Preact port for these?" Preact is what his zero-build pages use: an import map, a few vendored ES modules, no bundler. Focus trapping and arrow-key handling are the parts of those pages that are easy to get wrong by hand.

The React adapter passes nearly all of ui-sdk's tests on Preact

I ran ui-sdk's own React test suite, 2,991 tests, against the adapter on Preact 11. It passes 2,868; React passes 2,884. The failures showed me three places where Preact renders differently from React: it repeats ids across separate render roots, leaves removed attributes behind as empty strings, and reads an empty string as false on a boolean property. I corrected all three in an 83-line module, without touching the adapter.

What does not work on Preact:

  • React's <Activity>, which keeps a hidden page's state. Preact has no counterpart.
  • Concurrent useTransition. Preact's runs synchronously.
  • Preact 10, untested: the adapter expects ref as an ordinary prop, as React 19 and Preact 11 pass it.

I also left one small leak unfixed: after you open and close a popup many times, the browser keeps the last closed one in memory.

A page that uses it needs no build step and no TypeScript

I compiled ui-sdk to JavaScript once, one module per component, and put the result in the skill. Whoever writes the page, a person or an agent, then needs only an HTML file. In it they map Preact and the components with an import map and write the markup with HTM, tagged template strings in place of JSX that the browser runs as written. They install nothing and compile nothing: they run scripts/vendor.sh --ui-sdk to copy the files into vendor/, and this is a complete page with an accessible dialog:

<script type="importmap">
{ "imports": {
  "preact": "./vendor/preact.module.js",
  "preact/hooks": "./vendor/hooks.module.js",
  "preact/compat": "./vendor/compat.module.js",
  "preact/jsx-runtime": "./vendor/jsx-runtime.module.js",
  "preact/compat/jsx-runtime": "./vendor/compat-jsx-runtime.module.js",
  "htm": "./vendor/htm.module.js",
  "ui-sdk/": "./vendor/ui-sdk/"
} }
</script>
<script type="module">
  import { h, render } from "preact"
  import htm from "htm"
  import {
    Dialog, DialogTrigger, DialogContent, DialogTitle, DialogClose
  } from "ui-sdk/dialog.js"
  const html = htm.bind(h)

  render(html`
    <${Dialog}>
      <${DialogTrigger}>Open<//>
      <${DialogContent}>
        <${DialogTitle}>Hello from a static page<//>
        <${DialogClose}>Close<//>
      <//>
    <//>`, document.body)
</script>

I served that page from a plain static file server and clicked through it: the dialog opens, holds focus inside it, closes on Escape and puts focus back on its button. To publish it, an agent commits the HTML file and the vendor/ folder to a repository with GitHub Pages turned on, or uploads them to any other static host. Nobody runs a server or a build job.

The developing-preact skill now carries all 55 components

developing-preact is the skill Claude loads when you ask it for a Preact page like the one above. When Claude uses a dialog, it imports ui-sdk/dialog.js, and your visitor's browser downloads only the dialog's code: 16.8 KB gzipped for a button, 42.7 KB for a dialog. To choose a component, Claude reads the skill's list of all 55, with what each is for and its parts. When it needs a component's full documentation, it fetches that page from ui-sdk's npm package. It sets up the page's files with vendor.sh, which now brings in Preact 11.

Every upstream example runs on the showcase page

ui-sdk on Preact shows all 578 React examples from ui-sdk's repository, which I compiled once and Preact renders, with each example's source under it. The menubar, the search palette (Ctrl/⌘ K) and the source panels are ui-sdk components too. I restyled it in this site's palette, and the axe-core accessibility checker finds no contrast violations on any of its pages in light or dark.

The showcase itself did need a build step: its examples are Vercel's React code, written in TypeScript and JSX, and I had to compile them into JavaScript once before a browser could run them. Pages that Claude writes with the skill need none.

The test results, the fixes and the build scripts are in oaustegard/experiments.