Tooling

Preview

unframework preview shows every example and component on every target side by side, with controls for their props, and preview build writes it as a static site.

The preview lets you see a component on every target at once while you work on it. Think of a button you restyle in React and only later find too narrow in Svelte, a prop you rename that Angular no longer reads, or an agent asked for a screenshot of a card in seven frameworks that opens seven apps to take it.

unframework preview starts one dev server per target your unframework.config.ts names, and a page that shows the selection in one labelled frame per target. Pick an example or a component in the sidebar, and change a component's props in the controls panel: every target renders the same thing with the same props.

This page walks you through it. We'll look at:

  • Running it with unframework preview.
  • What it shows: your examples and your components.
  • The page: the sidebar, the canvas, the controls panel and the keyboard.
  • Example metadata: the category, title, description and order of each example.
  • Controls: the props the preview can set.
  • How it works: the servers, the frames and what it writes.
  • Building a static preview with unframework preview build.
  • Deploying it to any static host.

Run it

unframework preview comes with @uxfront/unframework, and needs @unframework.dev/visual and vite in your project, beside what unframework visual needs. The sample design system runs it from a script of its package.json:

package.json
    "preview": "unframework preview",

It prints the page's URL, then each target's server, and runs until you press Ctrl+C, which stops every server. These are its options:

OptionWhat it does
--target <t>Shows one target, and can be repeated. By default it shows every target of your configuration.
--port <n>The page's port. By default the system picks a free one, and each target's server always does.

It exits 0 once you stop it, and 2 on a usage or configuration error, a project with no example and no component, or a package it needs that isn't installed.

The preview is for your machine while you develop: every server listens on 127.0.0.1 only. Each target's compiler stack, like Angular's, comes from package.resolveFrom, as for unframework test.

What it shows

The sidebar lists your examples first, then your components. An example is a *.example.uf.tsx file with no props, found as unframework visual finds it. A component is the default export of a .uf.tsx file under srcDir, an example excepted. A file with no default export, or one that doesn't compile, isn't listed, and unframework check says why.

The page opens on the first example, and keeps the selection in its URL, so a reload or a link shows the same thing. Each frame's caption names its target and says whether it rendered, or why it failed.

A component renders with props alone, so its slots are empty and its models keep their defaults. To see a component with content, write an example that fills it, as examples/Buttons.example.uf.tsx does for Button.

The page

The page has three parts, side by side:

  • The sidebar holds your examples as a tree of their categories, and your components below it, by their paths. The filter at the top keeps the items whose name, or whose group's name, holds what you type.
  • The canvas shows the selection's title and description, and one frame per target. Targets above the frames shows them all side by side, or one at a time at the canvas's full size. A preview of one target shows it at the canvas's full size from the start, with no Targets switch.
  • The controls panel holds the selected component's controls, and names the props it can't set.

In a narrow window, the three stack: the sidebar, then the canvas, then the controls.

The page follows your system's light or dark setting. The moon button at the top of the sidebar switches between the two, and the page keeps your choice for the next time you open it. The frames keep a white page in both, since your components bring their own colours.

Everything works from the keyboard. Press ? to list these shortcuts on the page:

KeyWhat it does
/Moves to the filter.
EscClears the filter.
↓ in the filterMoves to the first item of the tree.
↑ and ↓Move through the tree.
← and →Close or open a group, or move out of or into it.
Home and EndMove to the tree's first or last item.
EnterShows the item, or opens or closes a group.
?Lists the shortcuts.

/ and ? do nothing while you type in a field.

Example metadata

The page lists your examples under their categories, by their titles. A doc comment on an example's default export sets them:

src/components/button/examples/ButtonColors.example.uf.tsx
/**
 * Every colour the theme defines, on the solid variant.
 * @category Components/Actions/Button
 * @title Colors
 * @order 2
 */
export default function ButtonColors() { … }

The comment has to sit directly on export default. Its text is the example's description. These are the tags it reads, and it ignores any other:

TagWhat it setsWithout it
@categoryThe groups the example sits in, outermost first, separated by /.The example's directory, or its parent's when the directory is examples.
@titleThe example's name in the list.The file name in words, without the category's own words in front.
@orderWhere it sits among the others, as a number: lower comes first.After every example that has one.

So without a comment, src/components/button/examples/ButtonColors.example.uf.tsx is Colors in Button, and src/components/field-group/examples/FieldGroupDefault.example.uf.tsx is Default in Field Group: the directory's name in title case, with - and _ as spaces. An example at your project's root, or in a root examples/, is in Examples.

Examples sort by @order, then by title, then by id. An empty @category or @title, an @order that isn't a number, or a tag given twice is a warning, UF7012, which the preview prints when it starts, and preview build when it builds. It then uses the value it derives instead.

The comment changes nothing that renders, so unframework visual doesn't read it, and an example keeps its id and its baselines.

Controls

A component gets one control for each prop whose type the preview can set:

Prop typeControl
booleanA checkbox
stringA text field
numberA number field
A union of string literalsA list of its values

The type can be an alias, even one imported from another file. The sample design system's Button takes a variant?: ButtonVariant, from its src/types.ts:

src/types.ts
export type ButtonVariant = "primary" | "secondary";

So its variant gets a list of primary and secondary. Change it, and every frame renders the button again with the new value, in place.

An optional prop starts unset, so the component's own default applies, and its control offers "(default)" to go back to it. A blank text or number field leaves an optional prop unset too. A required prop starts at false, an empty string, 0 or the first value of its union.

A prop of any other type, like a function, an object or a union of numbers, gets no control. The page names it, with its type.

How it works

Each target gets a Vite dev server of its own, built the way unframework test builds a browser project: the plugins of your config's vite, like a styling engine's, then the Unframework plugin for that target, then the target's own plugins, in that order within each of Vite's enforce groups. Each listens on a port of its own, so each frame has an origin of its own, and the frameworks never share a page. The page sends each frame the selection and its props with postMessage, and each frame mounts it with that target's mount adapter, the one the tests use. Astro has no client runtime, so its frame asks its own server to render on the server, and inserts the HTML.

Each server calls vite with its target and mode: "preview", for plugins of its own, and merges the other keys it returns into its config, as a test project does. It refuses the same keys, server.host, server.port and server.hmr among them, so the preview never listens beyond your machine.

The preview writes nothing beside your sources. Vite keeps each server's cache in node_modules/.vite, and Angular's compiler keeps its scratch in .uf-tmp/, in the directory its stack resolves from.

The first time a target meets a dependency it hasn't bundled yet, Vite bundles it and reloads that frame. The frame then asks for the selection again, so you don't have to do anything.

From a script, startPreview({ root, targets?, port?, toolchainDirs? }) from @unframework.dev/visual starts the same servers. It resolves to { url, frames, diagnostics, close } once every one listens: url is the page's, frames lists each target's origin and port, diagnostics holds the UF7012 warnings of your examples' doc comments, and close() stops them all. That's how an agent takes a screenshot of the page with Playwright, then stops the preview.

Build a static preview

unframework preview build writes the same preview as a static site, so you can publish it for the people who use your components, or give each pull request a link to it. It builds each target's frame with Vite, on the configuration its dev server uses, and writes the page that frames them beside them:

unframework preview build --out dist/preview

It prints any UF7012 warning of your examples, then where it wrote the site and the targets it built, and exits 0. These are its options:

OptionWhat it does
--target <t>Builds one target, and can be repeated. By default it builds every target of your configuration.
--out <dir>The site's directory, relative to your project. By default it's .unframework/preview, which examples are never under.

The build empties --out first, so it refuses your project's directory, a directory above it, and one that isn't empty and that no earlier build wrote. Those refusals exit 2, like a usage or configuration error, a project with nothing to show, or a build that fails.

The site is the page as index.html, and one directory per target, like react/ and vue/, with that target's frame as frame.html. Every URL in it is relative, so a static host serves it at any path, with no rewrites and no server. Open it at its directory's URL with the final slash, like https://example.com/preview/: without it, the page's relative URLs resolve from the directory above.

It runs what the dev preview runs, with three differences:

  • Every frame shares the page's origin, so the frames share storage and cookies. An example that reads localStorage can see what another target's frame wrote there. A frame answers only a page of its own origin, so another site can't frame it and drive it.
  • Astro shows each entry with its first props only. The site has no server to render Astro, so the build renders each example and each component once, with the props the page first sends it, and the Astro frame shows that render. Change a control, and the Astro frame says it can't render other props, while every other target renders them. Go back to the first values, and it renders again.
  • The frames are development builds, as the dev servers serve, so they're bigger than a production build. A path under your project, or its repository, appears relative to it, so the site carries no path of the machine that built it.

From a script, buildPreview({ root, targets?, out?, toolchainDirs? }) from @unframework.dev/visual writes the same site, and resolves to { out, targets, diagnostics }, where diagnostics holds those warnings.

Deploy

The site is plain files, so any static host serves it. On Cloudflare, a Worker with static assets serves the directory, and Workers Builds builds it on every push and gives each pull request a preview URL. Add a script that builds it to your package.json:

package.json
    "preview:build": "unframework preview build --out dist/preview",

Then point a wrangler.json at the directory:

wrangler.json
{
  "name": "my-components-preview",
  "compatibility_date": "2026-11-01",
  "assets": { "directory": "./dist/preview" },
  "previews": {}
}

In the Worker's build settings, the build command is npm run preview:build, and the deploy command is npx wrangler deploy.

The decisions behind this page are ADR-0088, ADR-0110 and ADR-0111.

Copyright © 2026