Was ist Storybook?
Storybook ist ein Open-Source-Werkzeug zur isolierten Entwicklung, Dokumentation und zum Testen von UI-Komponenten. Es läuft als eigenständige Webanwendung parallel zur eigentlichen App und zeigt jede Komponente in einem sogenannten Canvas an – völlig losgelöst vom Rest der Anwendung, ohne Datenbankverbindungen, API-Aufrufe oder globale Zustände, die stören könnten.
Storybook wird von Teams bei Airbnb, IBM, BBC und Shopify eingesetzt und ist inzwischen das meistgenutzte Werkzeug für Design-System-Dokumentation in der JavaScript-Welt. Es unterstützt alle gängigen Frameworks: React, Vue, Angular, Svelte, Web Components und mehr.
Das Stories-Konzept und das CSF-Format
Eine Story beschreibt einen spezifischen Zustand einer Komponente. Ein Button könnte mehrere Stories haben: Primary, Secondary, Disabled, Loading. Jede Story ist eine JavaScript-Funktion, die die Komponente mit bestimmten Props rendert.
Das Component Story Format (CSF) ist der aktuelle Standard zum Schreiben von Stories. Eine Story-Datei exportiert ein Default-Objekt mit Metadaten und benannte Exporte für jede einzelne Story. Das Beispiel für eine Button-Komponente sieht so aus: Das Default-Export enthält title, component und optionale argTypes. Jeder benannte Export ist eine Story-Funktion, die ein Args-Objekt entgegennimmt. Mit Primary.args = { label: 'Klick mich', variant: 'primary' } definiert man die Standardwerte.
CSF 3 hat die Syntax weiter vereinfacht: Stories können nun als einfache Objekte geschrieben werden, ohne dass eine Render-Funktion nötig ist. Das reduziert Boilerplate erheblich und macht die Dateien übersichtlicher.
Wichtige Addons
Storybooks Kern ist bewusst schlank gehalten. Funktionalität wird über Addons hinzugefügt, die sich im Addon-Panel unterhalb des Canvas anzeigen:
- Controls: Erlaubt es, Props einer Komponente interaktiv über ein Formular zu ändern, ohne die Story-Datei anfassen zu müssen. Ideal zum Erkunden aller Zustände.
- a11y (Barrierefreiheit): Integriert
axe-coreund prüft automatisch jede Story auf Zugänglichkeitsprobleme. Verstöße werden direkt im Panel angezeigt. - Viewport: Ermöglicht das Testen von Komponenten in verschiedenen Bildschirmgrößen – von Mobiltelefon bis Desktop – per Dropdown.
- Interactions: Erlaubt das Schreiben von interaktiven Tests direkt in der Story, die im Canvas abgespielt werden können. Nutzt
@storybook/testing-libraryunter der Haube. - Docs: Generiert automatisch eine Dokumentationsseite mit API-Referenz aus den
argTypesund JSDoc-Kommentaren der Komponente.
Integration mit React, Vue, Angular und Svelte
Die Installation von Storybook in einem bestehenden Projekt ist dank des CLI-Befehls npx storybook@latest init in wenigen Minuten erledigt. Das CLI erkennt das verwendete Framework automatisch und installiert die passenden Abhängigkeiten.
Für React ist die Integration am ausgereiftesten. Storybook versteht TypeScript-Props nativ und generiert daraus automatisch die Controls-Felder. Bei Vue werden Single File Components (.vue) direkt unterstützt. Für Angular gibt es spezielle Unterstützung für Decorators und Module-Abhängigkeiten. Svelte-Komponenten können ebenfalls ohne Konfigurationsaufwand eingebunden werden.
Ein wichtiger Aspekt: Storybook läuft nicht im Kontext der Anwendung, sondern in einem eigenen Build. Globale Stile, Provider (z. B. Redux Store, Router) oder Theme-Konfigurationen müssen explizit in Decorators eingebunden werden. Diese Decorator-Pattern ermöglicht es, Wrapper-Komponenten zu definieren, die jede Story umschließen – analog zu den Providers in der eigentlichen App.
Chromatic: Visuelle Regressionstests
Chromatic ist ein cloudbasierter Dienst, der von den Storybook-Maintainern entwickelt wurde und sich nahtlos in Storybook integriert. Bei jedem Pull Request werden Screenshots aller Stories automatisch mit den Screenshots des Basisbranches verglichen.
Gibt es visuelle Unterschiede, werden diese Chromatic als Review-Aufgaben angezeigt. Entwicklerinnen und Entwickler müssen Änderungen explizit akzeptieren oder ablehnen. Das verhindert unbeabsichtigte visuelle Regressionen – etwa wenn eine CSS-Änderung unerwartete Auswirkungen auf andere Komponenten hat.
Für Open-Source-Projekte ist Chromatic bis zu 5.000 Snapshots pro Monat kostenlos. Die Integration in CI erfolgt über einen einfachen CLI-Befehl: npx chromatic --project-token=<token>.
Design-System-Dokumentation mit Storybook
Viele Unternehmen nutzen Storybook als lebendige Dokumentation ihres Design-Systems. Mit dem Docs-Addon und MDX-Dateien lassen sich reichhaltige Dokumentationsseiten erstellen, die Code-Beispiele, Designrichtlinien und interaktive Komponenten-Demos kombinieren.
MDX (Markdown + JSX) erlaubt es, Stories direkt in Dokumentationstexte einzubetten. So kann die Seite für eine Button-Komponente gleichzeitig erklärendes Text, Nutzungsrichtlinien und live interaktive Beispiele enthalten. Designerinnen und Designer können die Dokumentation im Browser betrachten, ohne auf Figma oder Confluence angewiesen zu sein.
Vergleich: Storybook vs. Alternativen
| Kriterium | Storybook | Styleguidist | Docz | Histoire |
|---|---|---|---|---|
| Framework-Unterstützung | React, Vue, Angular, Svelte, Web Components | Hauptsächlich React, Vue | React, Vue | Vue 3, Svelte |
| Addon-Ökosystem | Sehr groß (100+ Addons) | Gering | Mittel | Klein, wachsend |
| Visuelle Tests | Ja (Chromatic) | Nein | Nein | Nein |
| Barrierefreiheitstests | Ja (a11y-Addon) | Nein | Nein | Nein |
| MDX-Dokumentation | Ja | Markdown | Ja (MDX-first) | Markdown |
| Reifegrad/Community | Sehr hoch | Stabil, wenig aktiv | Wenig aktiv | Aktiv, aber klein |
| Interaktive Controls | Ja (Controls-Addon) | Begrenzt | Begrenzt | Ja |
FAQ zu Storybook
- Verlangsamt Storybook den Build meiner Anwendung?
- Nein. Storybook ist ein eigenständiges Projekt mit seinem eigenen Build-Prozess. Der Storybook-Build ist völlig unabhängig vom Produktionsbuild der Anwendung. In CI wird der Storybook-Build typischerweise als separater Job ausgeführt. Der Produktionsbuild der App bleibt unberührt.
- Kann ich Storybook in einem Monorepo verwenden?
- Ja, Storybook ist sehr gut für Monorepos geeignet. Man kann entweder ein gemeinsames Storybook für alle Pakete einrichten oder separate Storybooks pro Paket betreiben. Viele Design-System-Monorepos (z. B. mit Turborepo oder Nx) verwenden ein gemeinsames Storybook als zentrale Dokumentations- und Testumgebung.
- Wie unterscheiden sich Stories von Unit-Tests?
- Stories definieren Komponenten-Zustände für visuelle Überprüfung und Dokumentation. Unit-Tests prüfen das Verhalten der Komponente programmatisch. Mit dem Interactions-Addon können Stories jedoch auch automatisierte Interaktionstests enthalten. Beide Ansätze ergänzen sich: Stories bieten visuelle Kontrolle, Unit-Tests bieten logische Korrektheitsprüfung.
- Was kostet Chromatic für kommerzielle Projekte?
- Chromatic bietet eine kostenlose Stufe mit 5.000 Snapshots pro Monat und einem Nutzer. Kommerzielle Pläne beginnen ab etwa 149 US-Dollar pro Monat für unbegrenzte Nutzer und mehr Snapshots. Für Teams mit einem aktiven Design-System rentiert sich die Investition schnell, da visuelle Regressionen kostspielige Bugfixes verhindern.
Mehr Details findest du in der offiziellen Storybook-Dokumentation.