Vue Komponenten dokumentieren mit Storybook

1. Warum Vue Komponenten mit Storybook dokumentieren

Das größte Problem mit herkömmlicher Komponentendokumentation ist, dass sie vom tatsächlichen Code abweicht, sobald die erste Änderung an der Komponente gemacht wird und niemand die Zeit findet, die Doku zu aktualisieren. Vue Storybook löst dieses Problem grundlegend: Die Dokumentation ist Code. Jede Story ist eine JavaScript-Funktion, die die Komponente in einem bestimmten Zustand rendert. Wenn sich die Komponente ändert, reflektiert die Story diesen Zustand automatisch – oder der Build bricht, wenn die Props inkompatibel geworden sind.

Der zweite Vorteil von Vue Storybook ist die Entkopplung vom Anwendungskontext. Eine Komponente kann im Storybook vollständig isoliert entwickelt und getestet werden, ohne die gesamte Anwendung zu starten. Das ist besonders wertvoll in großen Projekten, in denen das Starten der Anwendung Minuten dauert und das Annavigieren zur richtigen Seite weitere Interaktionen erfordert. Im Storybook rendert die Komponente sofort in exakt dem Zustand, den der Entwickler testen möchte.

Für Teams mit separaten Designer- und Entwicklerrollen ist Vue Storybook die gemeinsame Sprache. Designer können Komponenten im Browser ausprobieren, verschiedene Zustände durchschalten, responsive Breakpoints testen und Accessibility-Probleme direkt im Storybook identifizieren – ohne Zugriff auf den Code oder eine lokale Entwicklungsumgebung. Das reduziert den Kommunikationsaufwand erheblich und macht Review-Zyklen kürzer, weil Designer und QA mit derselben Instanz arbeiten wie Entwickler.

2. Storybook für Vue 3 einrichten

Vue Storybook lässt sich in bestehende Vue-3-Projekte mit einem einzigen Befehl initialisieren: npx storybook@latest init. Das CLI erkennt automatisch das Framework, installiert die notwendigen Abhängigkeiten und erstellt eine initiale Konfiguration im Ordner .storybook/. Die zwei wichtigsten Dateien sind main.ts, die das Storybook konfiguriert, und preview.ts, die globale Decorators, Parameter und Plugins definiert, die für alle Stories gelten.

Die Konfiguration in .storybook/main.ts legt fest, in welchen Verzeichnissen Storybook nach Story-Dateien sucht, welche Addons geladen werden und welchen Vite-Konfigurationsoverride Storybook verwendet. Für Vue Storybook-Projekte mit Pinia, Vue Router oder eigenen Provide/Inject-Abhängigkeiten ist preview.ts der Ort, an dem diese Abhängigkeiten als globale Decorators bereitgestellt werden. Ein Decorator ist eine Wrapper-Funktion, die jede Story in einen Kontext einbettet – zum Beispiel in einen Pinia-Store oder einen Vue-Router-Kontext.

// .storybook/preview.ts
// Global Storybook configuration for Vue 3 with Pinia and router
import { setup } from '@storybook/vue3'
import { createPinia } from 'pinia'
import { createRouter, createMemoryHistory } from 'vue-router'
import type { Preview } from '@storybook/vue3'

// Install Pinia and Router globally for all stories
setup((app) => {
  app.use(createPinia())
  app.use(createRouter({
    history: createMemoryHistory(),
    routes: [{ path: '/:pathMatch(.*)*', component: { template: '<div/>' } }],
  }))
})

const preview: Preview = {
  parameters: {
    // Enable auto-generated docs tab from JSDoc comments and prop types
    docs: { autodocs: 'tag' },
    // Restrict responsive viewport options to standard breakpoints
    viewport: {
      viewports: {
        mobile: { name: 'Mobile', styles: { width: '375px', height: '812px' } },
        tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' } },
        desktop: { name: 'Desktop', styles: { width: '1440px', height: '900px' } },
      },
    },
    // Enable accessibility checks by default in all stories
    a11y: { config: { rules: [{ id: 'color-contrast', enabled: true }] } },
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#0f172a' },
        { name: 'slate', value: '#f8fafc' },
      ],
    },
  },
}

export default preview

3. Die erste Story: Component Story Format 3

Das Component Story Format 3 (CSF3) ist der aktuelle Standard für Vue Storybook-Stories. Eine Story-Datei exportiert eine Default-Metadaten-Objekt (meta) und benannte Exporte für jede Story-Variante. Die Meta-Objekt definiert die Komponente, den Titel in der Storybook-Sidebar und globale Args für alle Stories in der Datei. Jeder benannte Export ist eine Story, die die Komponente in einem spezifischen Zustand rendert. Die Reduktion auf ein einzelnes Objekt – ohne render-Funktionen oder wrapper-Template-Strings – macht CSF3-Stories deutlich lesbarer als frühere Formate.

In Vue Storybook spielen Args die zentrale Rolle: Args sind die Props, mit denen die Komponente gerendert wird. Storybook leitet die verfügbaren Args automatisch aus den TypeScript-Typen oder den definierten defineProps-Deklarationen der Vue-Komponente ab. Das bedeutet, dass keine separate Dokumentation der Props notwendig ist – Storybook generiert die Controls-UI aus dem Komponentencode selbst. JSDoc-Kommentare an den Props erscheinen als Beschreibungstexte in der Controls-Tabelle.

4. Controls: Props interaktiv erlebbar machen

Controls sind das interaktivste Feature von Vue Storybook. Jede Prop einer Vue-Komponente erhält automatisch ein passendes Control-Widget in der Storybook-UI: Boolean-Props bekommen einen Toggle, String-Props ein Textfeld, String-Unions bekommen ein Select-Dropdown, Number-Props einen Slider oder ein Zahlenfeld. Damit können Entwickler, Designer und Tester die Komponente direkt im Browser in verschiedenen Zuständen erkunden, ohne Code ändern zu müssen. Ein Button-Komponente lässt sich so interaktiv in allen Varianten – primary, secondary, disabled, loading – durchklicken.

Für komplexere Props wie Arrays oder Objekte kann die Controls-Konfiguration in der argTypes-Sektion der Story-Metadaten angepasst werden. Dort lässt sich der Control-Typ explizit setzen, der Bereich für numerische Controls einschränken und Optionen für Select-Controls definieren. Für Vue Storybook-Projekte mit einer Design-Token-Library empfiehlt sich, Farbwerte als Control-Optionen zu erfassen, sodass Designer die Komponente mit dem tatsächlichen Token-Vokabular testen können, statt hexadezimale Farben einzutragen.

// src/components/Button/Button.stories.ts
// CSF3 story file for the Button component with controls and variants
import type { Meta, StoryObj } from '@storybook/vue3'
import Button from './Button.vue'

// Meta defines component and global defaults for all stories in this file
const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  tags: ['autodocs'],  // Auto-generate a Docs page from props and JSDoc
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost', 'danger'],
      description: 'Visual style variant of the button',
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
    onClick: { action: 'clicked' },  // Log click events in Actions panel
  },
  args: {
    // Default args shared by all stories in this file
    label: 'Button Label',
    variant: 'primary',
    size: 'md',
    disabled: false,
    loading: false,
  },
}

export default meta
type Story = StoryObj<typeof meta>

// Each named export is one story — rendered with the given args
export const Primary: Story = {}

export const Secondary: Story = {
  args: { variant: 'secondary' },
}

export const Loading: Story = {
  args: { loading: true, label: 'Wird geladen...' },
}

export const Disabled: Story = {
  args: { disabled: true },
}

// Story with render function for complex template scenarios
export const WithIcon: Story = {
  render: (args) => ({
    components: { Button },
    setup() { return { args } },
    template: `<Button v-bind="args"><template #icon>★</template></Button>`,
  }),
}

5. Addons: Accessibility, Viewport und Docs

Der eigentliche Mehrwert von Vue Storybook entfaltet sich durch das Addon-Ökosystem. Das Accessibility-Addon (@storybook/addon-a11y) führt automatisch axe-Prüfungen auf jeder Story aus und zeigt Accessibility-Verstöße direkt im Storybook-Panel an. Das ist für Design-Systeme besonders wertvoll: Jede neue Komponente wird automatisch auf WCAG-Konformität geprüft, ohne separate Test-Infrastructure. Contrast-Ratio-Fehler, fehlende ARIA-Labels und falsche Heading-Hierarchien werden sofort sichtbar gemacht.

Das Docs-Addon generiert aus Stories, JSDoc-Kommentaren und TypeScript-Prop-Typen automatisch eine strukturierte Dokumentationsseite für jede Komponente. Diese Seite enthält eine interaktive Props-Tabelle, alle Story-Varianten in einer Übersicht und manuell geschriebene MDX-Inhalte, falls gewünscht. Das Ergebnis ist eine Vue Storybook-Dokumentation, die immer mit dem aktuellen Code synchron ist und keinen separaten Pflegeaufwand erfordert. Das Viewport-Addon macht es einfach, Komponenten bei verschiedenen Bildschirmbreiten zu testen, ohne Browser-Devtools zu öffnen.

6. Composables und State in Stories testen

Eine häufige Herausforderung in Vue Storybook-Projekten ist das Testen von Komponenten, die auf Composables mit externem State angewiesen sind – API-Calls, Pinia-Stores oder globale Context-Werte. Die sauberste Lösung ist das Mocking auf Story-Ebene: Statt den echten API-Aufruf auszuführen, wird in der Story ein Mock-Handler registriert, der die erwartete Antwort zurückgibt. Das Mock Service Worker Addon (msw-storybook-addon) integriert MSW direkt in Storybook, sodass API-Aufrufe auf der Network-Schicht abgefangen werden – genau wie in echten Tests, ohne den Produktionscode zu ändern.

Für Pinia-Stores in Vue Storybook ist ein Story-Level-Decorator die eleganteste Lösung. Der Decorator erstellt einen frischen Pinia-Store, befüllt ihn mit dem für die Story relevanten State und stellt ihn der Komponente per provide bereit. Das erlaubt, Komponenten in einem eingeloggten Zustand, einem Fehlerzustand oder einem leeren Zustand zu dokumentieren, ohne die Store-Logik in der Story nachzubauen. Jede Story zeigt genau den Zustand, den sie kommunizieren soll – vollständig reproduzierbar, jederzeit.

7. Visual Regression Tests mit Chromatic

Visual Regression Tests sind in Vue Storybook-Projekten mit Chromatic besonders einfach zu implementieren. Chromatic ist ein Cloud-Service, der bei jedem Commit Screenshot-Vergleiche aller Stories durchführt und Entwickler auf visuelle Veränderungen hinweist. Der Unterschied zu anderen Visual-Testing-Lösungen: Chromatic nutzt Storybook direkt als Test-Suite. Keine separate Test-Konfiguration, keine Browser-Steuerung per Puppeteer – die bereits vorhandenen Stories werden zum vollständigen Visual-Test-Katalog.

Das Workflow in einem Vue Storybook-Projekt mit Chromatic ist: Developer pusht, CI baut Storybook, Chromatic vergleicht alle Stories mit dem aktuellen Baseline-Screenshot und markiert Änderungen. Der Entwickler überprüft die markierten Diffs im Chromatic-Dashboard und akzeptiert beabsichtigte Änderungen oder lehnt unbeabsichtigte ab. Akzeptierte Änderungen werden zur neuen Baseline. Dieses Workflow verhindert versehentliche visuelle Regressionen, die in großen Komponentenbibliotheken häufig auftreten, wenn Änderungen an shared Styles unerwartete Auswirkungen haben.

8. Storybook in CI/CD-Pipelines integrieren

Die Integration von Vue Storybook in CI/CD-Pipelines hat drei wesentliche Komponenten: den Storybook-Build-Check, optionale Visual-Regression-Tests und das Deployment des statischen Storybooks als Review-Environment. Der Storybook-Build (storybook build) schlägt fehl, wenn Komponenten TypeScript-Fehler haben oder Stories sich nicht rendern lassen. Das macht den Build zu einem effektiven Quality-Gate: Stories, die auf fehlerhafte Props verweisen oder defekte Imports haben, blockieren den Merge.

Das Deployment des statischen Storybooks als Teil des CI-Prozesses gibt dem gesamten Team – Entwickler, Designer, QA, Product Owner – eine immer aktuelle Ansicht aller Komponenten in allen dokumentierten Zuständen. Dienste wie Chromatic, Netlify oder GitHub Pages können ein statisches Storybook direkt aus dem CI-Artefakt publizieren. Ein Link in der Pull-Request-Beschreibung zur aktuellen Storybook-Instanz des Branches macht Code-Reviews effizienter, weil Reviewer visuelle Veränderungen direkt im Browser beurteilen können, ohne lokale Entwicklungsumgebungen aufzusetzen.

9. Dokumentationsansätze im Vergleich

Für Vue Storybook ist der Vergleich mit anderen Dokumentationsansätzen instruktiv – nicht um Storybook zu verkaufen, sondern um den richtigen Ansatz für den richtigen Kontext zu wählen.

In der Praxis ergänzen sich Vue Storybook und VitePress am besten: Storybook für die interaktive Komponentendokumentation, VitePress für übergreifende Konzepte, Design-Entscheidungen und API-Dokumentation. Beide können mit denselben Quell-Komponenten und JSDoc-Kommentaren generiert werden, sprechen aber unterschiedliche Zielgruppen an – Storybook primär Entwickler und Designer im Daily-Workflow, VitePress für externe Nutzer der Library oder neue Teammitglieder.

10. Zusammenfassung

Vue Storybook ist mehr als ein Dokumentationstool – es ist eine Entwicklungsumgebung für Komponenten in Isolation. Stories in CSF3 sind wartbarer Code, keine veraltende Prosa. Controls machen Props interaktiv und geben Designern direkten Zugang zu Komponentenzuständen. Das Accessibility-Addon macht WCAG-Prüfungen zum Standard-Workflow. Visual Regression Tests mit Chromatic verhindern unbeabsichtigte visuelle Regressionen. Der Storybook-Build als CI-Gate stellt sicher, dass fehlerhafte Komponenten nicht unbemerkt in den Main-Branch gelangen.

Der wichtigste Faktor für ein erfolgreiches Vue Storybook-Projekt ist die Disziplin, Stories parallel zur Komponentenentwicklung zu schreiben – nicht nachträglich als separate Aufgabe. Wenn Storybook von Anfang an Teil des Workflows ist, werden Stories zu lebendiger Dokumentation, die das Team täglich nutzt und aktuell hält. Storybook schlägt dann von selbst an, wenn jemand eine Komponente bricht – und das ist der größte Wert des gesamten Systems.

11. FAQ: Vue Komponenten mit Storybook dokumentieren