@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:

vp install -D @vizejs/vite-plugin @vizejs/vite-plugin-musea vize

Usage

// vite.config.ts
import { defineConfig } from "vite";
import vize from "@vizejs/vite-plugin";
import { musea } from "@vizejs/vite-plugin-musea";

export default defineConfig({
  plugins: [
    vize(),
    musea({
      include: ["src/**/*.art.vue"],
      basePath: "/__musea__",
      previewCss: ["src/styles/main.css"],
      previewSetup: "musea.preview.ts",
    }),
  ],
});

Run your Vite dev server and open the gallery route:

vp dev

http://localhost:5173/__musea__

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 can live in vize.config.ts:

import { defineConfig } from "vize";

export default defineConfig({
  musea: {
    include: ["src/**/*.art.vue"],
    exclude: ["node_modules/**", "dist/**"],
    basePath: "/__musea__",
    inlineArt: false,
    storybookCompat: false,
  },
});

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

<!-- Button.art.vue -->
<script setup lang="ts">
defineArt("./Button.vue", {
  title: "Button",
  category: "UI",
  tags: ["button", "form"],
});
</script>

<art>
  <variant name="Primary" default>
    <Button variant="primary">Click me</Button>
  </variant>
  <variant name="Disabled">
    <Button disabled>Disabled</Button>
  </variant>
</art>

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.

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

<script setup lang="ts">
import { ref } from "vue";

defineArt("./Counter.vue", { title: "Counter" });

const count = ref(0);
</script>

<art>
  <variant name="Initial" default>
    <Counter :count="count" />
  </variant>
  <variant name="Interactive">
    <Counter :count="count" />
  </variant>
</art>

Use <script setup isolate="false"> when variants intentionally share one setup instance.

Legacy <art> 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:

musea({
  inlineArt: true,
});

Use <Self> in an inline <art> block to render the host component.

Preview Setup

musea({
  previewCss: ["src/styles/main.css", "src/styles/musea-preview.css"],
  previewSetup: "musea.preview.ts",
});

// musea.preview.ts
import type { App } from "vue";

export default function setup(app: App) {
  // Install vue-router, vue-i18n, stores, or design-system plugins here.
}

Design Tokens

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

musea({
  tokensPath: "src/tokens.json",
});

Commands

# Start dev server
vp dev

# Build gallery
vp build

# Run visual regression snapshots
vp exec musea-vrt --base-url http://localhost:5173

# Update local baselines
vp exec musea-vrt --update

# CI mode with JSON output
vp exec musea-vrt --ci --json

# Run a11y audits alongside snapshots
vp exec musea-vrt --a11y

# Approve failed snapshots
vp exec musea-vrt approve

# Remove orphaned snapshots
vp exec musea-vrt clean

# Generate an art-file draft
vp exec musea-vrt generate src/components/Button.vue

License

MIT