nmnmcc Preview
Use Preview to make important UI states explicit and repeatable. Keep each definition close to its source, run it with the project's real Vite and framework setup, and inspect the result during development, review, or CI.
Preview gives the work these useful properties:
- It runs the project's Vite and framework setup instead of a copied demo.
- It supports both an isolated Component and a real Application route.
- It captures each explicit
emit("state-name")call instead of guessing with a delay. - It gives emitted states, viewports, and matrix variants stable, readable artifact paths.
- It uses the same generator in Vite development, local commands, and CI.
Work in this order
- Inspect the target project's package manager, versions, Vite config, framework, route system, existing Preview setup, and target UI.
- Read Setup and target choice. Choose a Component only when it can run without route-only state. Otherwise choose an Application.
- Read the guide for the chosen target. Install the core package, any needed
Component adapter, Playwright, and Chromium. Skip Chromium only after checking
that the environment supplies and configures the matching browser. Add the
plugin, the smallest working definition, and one named viewport. Put
await emit("default")anddone()inside an exact lowercasepreview: { ... }block. Emit only after the named pixels are present. - Run the local Preview command for the new or changed file. Open every PNG
that the task depends on. When inspection is enabled, read its
README.mdand open each relevant overview or evidence image. Check the subject, state, viewport, clipping, fonts, bounds, checks, and other visible details. A successful command alone is not visual proof. - Fix the UI or preview and generate again until the image is right. Then run
the project's type check. Run its production build when normal application
source contains a
preview:block.
Report a version mismatch instead of silently changing the project's Node, Vite, framework, or Playwright version. Upgrade only when the task permits it.
Put each part in the right place
| Part | Place | Purpose |
|---|---|---|
| Preview Vite plugin | vite.config.*, after the framework plugin |
Discover files, run capture, and remove capture-only blocks from builds |
| Component definition | *.preview.{js,jsx,ts,tsx} beside the component |
Mount one isolated subject with the matching adapter |
| Component lifecycle | A preview-only wrapper, or optional callbacks in the subject when it knows each wanted state | Emit named states and end capture inside preview: { ... } |
| Application definition | *.preview.{js,jsx,ts,tsx} beside the route |
Open one final same-origin route location |
| Application lifecycle | The real route component | Emit named route states and end capture inside preview: { ... } |
| Shared setup | A small local preview template module | Add common CSS, providers, theme, or locale once |
| Captured artifact | A sibling .preview/ tree by default |
Keep clean images and optional inspections close to their source |
Read only the needed guides
- Read Component previews for plain DOM, React, Vue, Svelte, preview-only wrappers, shared templates, and cleanup.
- Read Application previews for React Router, SvelteKit, vinext, route locations, and route capture lifecycle.
- Read Capture and variants for discovery, Playwright settings, viewport presets, full pages, and matrices.
- Read Layout inspection for coordinate axes, bounds, overlap evidence, exact checks, domain JSON, overview images, and per-finding evidence.
- Read Artifacts and CLI for commands, output paths, cleaning, versioning, CI, visual proof, and fault finding.
Read more than one guide when the result crosses those areas.
Keep these rules
- Preserve the target application's setup. Do not replace its router, providers, loaders, server rendering, or framework plugin.
- Keep the first config to the required named viewports. Add file filters, Playwright overrides, cleaning, versioning, or matrices only for a stated need.
- Put Preview after the framework plugin. With vinext, do not add another React or React Server Components plugin.
- Keep Component and Application targets distinct. Do not mock route-only modules to force them into a Component.
- Give every state a lowercase name that uses letters, numbers,
_, or-. Await eachemit(name)call. Do not run emits at the same time or reuse a name in one capture. - Call
done()once after at least one completed emit. Do not use a fixed sleep as a lifecycle signal. - Put all capture-only lifecycle work for Component and Application targets
in an exact lowercase
preview: { ... }block. This includes code in a preview-only wrapper. Put no product work in that block. - Keep Application locations and browser navigation on the Vite origin.
- Never import
@nmnmcc/preview/internal/runner. It is private to the plugin. - Make browser setup explicit. Install Playwright's matching Chromium in a normal environment. Do not install it in a Nix or Devenv shell that already supplies and configures the matching browser.