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

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">
import Button from "./Button.vue";
</script>

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

Common <art> attributes:

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