@vizejs/vite-plugin-musea weekly downloads statistics

@vizejs/vite-plugin-musea

Vite plugin for Musea - Vue component gallery and documentation.

Installation

Install vp once from the Vite+ install guide, then add the package:

Usage

Run your Vite dev server and open the gallery route:

Musea middleware is intended for the local Vite dev server and trusted development networks. Do not expose /musea directly on the public internet unless it is protected by your own network controls or authentication layer.

Shared defaults live in vue.musea in your existing vite.config.*. With Vite+, retain your existing options and add Vue settings through the helper:

Direct musea() options override shared config. Pass preview-only options such as previewCss, previewSetup, tokensPath, theme, and storybookOutDir directly to the plugin.

Art File Format

defineArt(source, options) is a compiler macro. It declares the Vue component Musea should render and the metadata shown in the gallery. Prefer a relative component path string; the macro call is removed and Musea generates the component import. The Musea language server uses the same source for path completion, missing-file diagnostics, go-to-definition, and prop/slot inference.

The source may be a .vue, .ts, .tsx, .js, or .jsx file. For render-function components, Musea reads statically declared runtime props and emits for the analysis and props panel.

Vue 3.5.41 does not apply a component prop literally named proto. Retaining its raw editor value does not make it a rendered prop. Avoid this prop name; #8533 tracks explicit editor refusal and release acceptance.

TypeScript and Editor Setup

Add the client types once, usually in src/env.d.ts:

If your project type-checks .art.vue files with Volar or vue-tsc, include the extension in tsconfig.json:

Root state is variant-local by default, so each variant gets its own refs, computed values, and composable calls:

Use when variants intentionally share one setup instance.

Legacy metadata attributes are still supported:

| Attribute | Purpose |

| title | Display name in the gallery | | component | Relative source component path | | category | Sidebar grouping | | status | Optional status badge | | tags | Search and filtering tags | | action-events | Comma-separated events to capture | | capture-mousemove | Include mousemove in captured actions |

Enable inline art when examples should live inside the component file:

Use in an inline block to render the host component.

Preview Setup

Musea's preview scaffold styles are emitted in a low-priority cascade layer, so layered CSS from frameworks such as Tailwind v4 can still override them when loaded through previewCss.

Design Tokens

Expose a Style Dictionary-compatible token file in the gallery:

Tailwind v4 theme variables can also be used as the token source:

tokensPath reads tokens for the gallery and token APIs. Use previewCss separately when that CSS file should also be loaded inside component preview iframes.

Token previews are inferred from token type, path, and referenced token metadata. Spacing, opacity, radius/round, and z-index tokens render previews by default. Add custom rules when your token names use project-specific categories:

Commands

License

MIT