# 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`](/docs/tooling/visual#run-it) needs. The sample design system runs it from a script of its `package.json`:

<!-- prettier-ignore -->
```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:

| Option         | What 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`](/docs/tooling/configuration#fields), as for `unframework test`.

## What it shows

The sidebar lists your examples first, then your components. An example is a [`*.example.uf.tsx` file](/docs/tooling/visual#examples) 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](#example-metadata), 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](#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:

| Key               | What it does                                      |
| ----------------- | ------------------------------------------------- |
| `/`               | Moves to the filter.                              |
| `Esc`             | Clears the filter.                                |
| `↓` in the filter | Moves 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 `End`  | Move to the tree's first or last item.            |
| `Enter`           | Shows 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:

<!-- prettier-ignore -->
```tsx [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:

| Tag         | What it sets                                                       | Without it                                                                 |
| ----------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `@category` | The groups the example sits in, outermost first, separated by `/`. | The example's directory, or its parent's when the directory is `examples`. |
| `@title`    | The example's name in the list.                                    | The file name in words, without the category's own words in front.         |
| `@order`    | Where 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](/docs/reference/diagnostics#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`](/docs/tooling/visual#examples) 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 type                  | Control              |
| -------------------------- | -------------------- |
| `boolean`                  | A checkbox           |
| `string`                   | A text field         |
| `number`                   | A number field       |
| A union of string literals | A 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`:

<!-- prettier-ignore -->
```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`](/docs/tooling/testing#styling-engines-and-other-vite-plugins), 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](/docs/reference/diagnostics#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:

<!-- prettier-ignore -->
```bash
unframework preview build --out dist/preview
```

It prints any [UF7012](/docs/reference/diagnostics#UF7012) warning of your examples, then where it wrote the site and the targets it built, and exits `0`. These are its options:

| Option         | What 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`:

<!-- prettier-ignore -->
```json [package.json]
    "preview:build": "unframework preview build --out dist/preview",
```

Then point a `wrangler.json` at the directory:

<!-- prettier-ignore -->
```json [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](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0088-unframework-preview.md), [ADR-0110](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0110-examples-carry-metadata-in-a-doc-comment.md) and [ADR-0111](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0111-unframework-preview-build-writes-a-static-site.md).
