Build bulletproof UI components faster

Storybook is a development environment for UI components. It allows you to browse a component library, view the different states of each component, and interactively develop and test components. Find out more at https://storybook.js.org.

View README for:

Table of contents

• 🚀 Getting Started
• 📒 Projects
  • 🛠 Supported Frameworks & Examples
  • 🚇 Sub Projects
  • 🔗Addons
• 🏅 Badges & Presentation materials
• 👥 Community
• 👏 Contributing
  • 👨‍💻 Development scripts
  • 💵 Backers
  • 💸 Sponsors
• :memo: License

Getting Started

Visit Storybook's website to learn more about Storybook and to get started.

Documentation

Documentation can be found Storybook's docs site.

Examples

Here are some featured examples that you can reference to see how Storybook works: https://storybook.js.org/showcase

Storybook comes with a lot of addons for component design, documentation, testing, interactivity, and so on. Storybook's API makes it possible to configure and extend in various ways. It has even been extended to support React Native, Android, iOS, and Flutter development for mobile.

Community

For additional help, join us in the Storybook Discord.

Projects

Supported Frameworks

Framework	Demo
React
Vue
Angular
Web components
React Native	-
HTML
Ember
Svelte
Preact
Marionette.js	-
Android, iOS, Flutter

Sub Projects

• CLI - Streamlined installation for a variety of app types
• examples - Code examples to illustrate different Storybook use cases

Addons

See Addon / Framework Support Table

Deprecated Addons

In order to continue improving your experience, we have to eventually deprecate certain addons in favor of new, better tools.

If you're using info/notes, we highly recommend you to migrate to docs instead, and here is a guide to help you.

If you're using contexts, we highly recommend you to migrate to toolbars and here is a guide to help you.

Badges & Presentation materials

We have a badge! Link it to your live Storybook example.

[![Storybook](https://cdn.jsdelivr.net/gh/storybookjs/brand@main/badge/badge-storybook.svg)](link to site)

If you're looking for material to use in your presentation about storybook, like logo's video material and the colors we use etc, you can find all of that at our brand repo.

Community

• Tweeting via @storybookjs
• Blogging at storybook.js.org and Medium
• Chatting on Discord
• Streaming saved at Youtube

Contributing

We welcome contributions to Storybook!

• 📥 Pull requests and 🌟 Stars are always welcome.
• Read our contributing guide to get started, or find us on Discord, we will take the time to guide you.

Looking for a first issue to tackle?

• We tag issues with when we think they are well suited for people who are new to the codebase or OSS in general.
• Talk to us, we'll find something to suits your skills and learning interest.

Development scripts

Storybook is organized as a monorepo using Lerna. Useful scripts include:

yarn bootstrap

Installs package dependencies and links packages together - using lerna

yarn lint

boolean check if code conforms to linting rules - uses remark & eslint

• yarn lint:js - will check js
• yarn lint:md - will check markdown + code samples
• yarn lint:js --fix - will automatically fix js

yarn test

boolean check if unit tests all pass - uses jest

• yarn run test --core --watch - will run core tests in watch-mode

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

License

MIT

-the end-

Release Process

A Storybook release process based on Semver. In short:

1. Merge all PRs into next, which is the default branch. Cherry-pick bugfix PRs into main, which is the stable release.

2. Every week: release patch releases off main to the NPM tag latest, and alpha releases off next to the NPM tag next (as e.g. 4.1.0-alpha.0).

3. Every month or two, merge next into main and release a minor/major version according to semver. We set minor release dates as soon as we have feature clarity and manage to those dates:

   • Date should be a Monday so if we slip we don't get pushed into the weekend
   • T-3wk:
     • Draft announcement and socialize
     • Announce dates in #maintenance so people can react
   • T-1wk:
     • If you want your feature in the release, it should already be released on next by this time
     • Create release branch and only cherrypick bugfixes
     • Set up launch plan

Motivation

During the Storybook 3.x transition we've undergone a series of growing pains as we've opened up the development process. We've had questions about:

1. how to adhere to semver?
2. how to do marketing releases (while adhering to semver)?
3. how to introduce significant new features (e.g. vue support, story hierarchy)?
4. how to converge on key design decisions (e.g. new addons API)?
5. how to schedule releases?
6. how to maintain quality/stability through the process?
7. how to pay down tech debt as we go?

This process attempts to address all these concerns in one shot.

Semver

Semver dictates three types of release:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

We'll do our best to adhere to Semver, but won't be religious about it. In particular, we may occasionally release small bits of new functionality in PATCH releases. We'll try our best to restrict breaking changes to MAJOR releases.

PATCH releases

Every bugfix should go out as soon as we've verified the fix, and based on the current rate of contribution, we should be issuing PATCH releases weekly. Eventually, we'll automate the process so that a release will go out every time a PR is merged into main, and we've already laid most of the groundwork for this.

MINOR releases

Every new feature, particularly significant ones (e.g. Vue support, deep hierarchy for stories) deserves more attention:

1. They should be well-tested by the community before we release.
2. They often have architectural implications for the entire Storybook ecosystem, so should be discussed thoroughly before release. Doing alpha releases allow us to test in the community without necessarily achieving agreement.
3. They often deserve proper marketing treatment (blog posts, release announcement, podcast, etc.)

Therefore we release alpha versions continuously on the NPM next tag to allow people to test out features as soon as they are ready.

In general, we should release 2-3 headline features per minor release for marketing purposes. Each headline feature should get its own blog post on the Storybook medium publication, and the release itself should also get a blog post.

MAJOR releases

We should avoid major releases, but won't hold ourselves back on this. Making storybook better is the prime directive, and if we have to make breaking changes to do it, we will. That said, MAJOR releases should have killer features that reward users for upgrading, and should not be used to scratch our own architectural itches -- unless those itches are really killing development in some meaningful way.

Blocking bugs

Most PATCH releases come from community members, who generously fix problems as they come up. However, there are also bugs that never get picked up and just sit there gathering upvotes and "me too" comments. We need a way to make sure that these bugs get addressed.

For every non-PATCH release, we nominate a small number of bugs that must be addressed before a release can go out by adding them to the milestone. For example, here's a list of blocking bugs for the 3.2 milestone.

Adding bugs to the milestone helps people looking for good ways to contribute, or to understand what is blocking the release so they can actually do something about it. Discussion about which bugs are critical happens in the #maintenance channel in our Slack

If you're experiencing a bug, the best way to make sure that it gets attention is to upvote it by adding a "thumbs-up" reaction in Github. This way important bugs quickly bubble to the top with a search.

The best way to make sure a bug gets addressed quickly is to fix it yourself and issue a PR. If the fix is good, we'll try to release it quickly in a patch release.

Decision-making

• For PATCH changes, all discussion can occur in issue/PR comments (and random slack chat as needed).
• For MINOR feature changes, there are multiple stages of discussion:
  • The feature may be discussed in an issue before it is implemented (ex: https://github.com/storybookjs/storybook/issues/151)
  • Once it's implemented, the discussion may occur on the PR (ex: https://github.com/storybookjs/storybook/pull/1329)
  • If people disagree on an implementation and it can't be resolved in discussion, they may issue alternative PR's with different ideas
  • Ultimately the maintainers will reach a consensus before merging the changes. There is no set process for this, but we're all adults.
  • Since MINOR features are released in alpha before they are fully released, new issues may be created by end users, etc.
• For MAJOR infrastructural changes, the discussion may take place over time, in gists, issues, slack discussions, etc.
  • Once the breaking changes have been reduced to an actual implementation, it looks pretty much like a feature release (only with higher stakes and probably a longer stabilization process).

FAQ's

How does my PR get merged?

• For PATCH PR's, any maintainer can review, test, approve, and merge it.
• For MINOR/MAJOR PR's, once a maintainer reviews, tests, and approves it, they should clear it with the other maintainers before merging it into the release branch.
• Once a release date has been set and we cut off merging, we'll create a temporary branch to hold that release so that it doesn't block merging to next.