Storybook for Svelte

Storybook, the most popular component workshop, is getting its biggest Svelte upgrade ever. Storybook for Svelte has been completely reworked and improves every facet of the experience from the way you write stories to the underlying implementation.

The new release, available in Storybook 6.2, includes:

• 🎁 Zero-config setup w/ built-in TypeScript support
• 📝 A Svelte-native story format for capturing component states
• 🎛 Auto-generated controls and documentation
• 📚 Updated tutorials and documentation

This is all in addition to the large ecosystem of development, testing, and documentation addons already available to Svelte users. Read on for a full tour of the new features!

Betting on Svelte

Storybook for Svelte (SB Svelte) was first released in 2018 and updated for Svelte 3 in 2019. It has grown steadily, but until recently has only had basic support in Storybook.

That’s all changing. First, Ernie Francis added auto-documentation support in SB6.1. Then Jérémie Brébec overhauled the entire package, documented it, and released a native Svelte syntax for component examples.

Now Svelte support in Storybook is truly first class, and adoption has grown as a result. NPM downloads of @storybook/svelte now account for over 10% of total Svelte usage. Svelte is awesome and we are proud to bet on its continued success.

Zero-config setup

To get started, run the following in the root of an existing Svelte project:

npx sb init

This detects the project type, installs @storybook/svelte, and adds some sample files to demonstrate the basics of Storybook. Running yarn storybook gives you the following zero-config setup:

When you navigate to Storybook locally, you’ll see examples of how to write Svelte stories, links to common configurations, as well as the “essential” addons that ship with Storybook. TypeScript support is built-in. Learn more in the official documentation.

Svelte-native format

In Storybook, a story is a code snippet that renders an example of a component in a specific state. Storybook now has a native story format for Svelte users, meaning you can write your stories in the same stylized Svelte SFC syntax that you’re used to.

<script>
  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
  import Button from './Button.svelte';
</script>

<Meta title="Button" component={Button}/>

<Template let:args>
  <Button {...args}/>
</Template>

<Story name="Primary" args={{primary: true}}/>

<Story name="Secondary" args={{primary: false}}/>

Under the hood, these native format stories are compiled to Component Story Format (CSF), an ESM-based standard for portable, reusable component examples. This means that the new stories are 100% compatible with the rest of the Storybook ecosystem.

Auto-generated controls and documentation

Storybook reads the docgen information from the Svelte compiler to automatically generate controls and documentation based on your stories and components.

The example from the previous section might generate the following UI for interactively exploring your component states:

It also results in component documentation with no extra work, which includes all of the key states laid out with props extracted from the component source:

Your component's controls and docs are always up to date because they're generated automatically from the source code. You don't need to keep track of your UI documentation whenever a component's API changes, Storybook does that for you.

Perfect for UI testing

When you build UIs in Storybook you get testing for free. Storybook revolves around the concept of stories, these capture the supported state of your UI components.

In development, you can manually confirm your stories “look right” and use a suite of addons to test your story in other dimensions like accessibility and mobile-friendliness.

In continuous integration, you can automatically detect both structural and visual changes in your stories using snapshot and visual testing respectively.

Testing your stories is so useful that multiple commercial services integrate with Storybook to run tests in the cloud and across browsers. Notably, Chromatic, created by Storybook maintainers, integrates tightly with Storybook and provides free automated publishing and visual diffing.

What’s more, your stories are portable across tools. Storybook pioneered the Component Story Format, an open standard for component examples based on JavaScript ES6 modules. That allows you to reuse stories for your unit and end-to-end tests – no lock-in.

200+ addons to choose from

Storybook’s been refining its cross-framework compatibility for years. This means that nearly all of Storybook’s hundreds of addons are available for Svelte users. Addons unlock superpowers like accessibility testing, design handoff integrations, styling utilities, and mocking for network requests.

Next steps

Storybook for Svelte is available now in 6.2. Install it by running the following command in the root of your project. Then check out the updated tutorial and reference docs.

npx sb init

To upgrade an existing project:

npx sb upgrade

Svelte native format is automatically included on fresh installations, but for upgrades you need to manually install it.

We’ve got big improvements planned for Svelte including:

• Tighter integration with Svelte build tools using pluggable builders
• Native Svelte MDX support once MDX v2 is released

Get involved

Storybook is maintained by 1,250+ open source contributors and guided by a steering committee of top maintainers.

Storybook for Svelte is maintained by Jérémie Brébec, who is responsible for most of the upgrades described in this post. Svelte native syntax was originally proposed by rixo. Storybook Docs support was added by Ernie Francis. Svelte support was originally contributed by Gavin King and upgraded to Svelte 3 by Cameron Stitt.

For an in-depth look at Svelte, check out Mark Volkmann's guide and his lengthier book which features Storybook.

If you are interested in contributing, check out Storybook on GitHub, create an issue, or submit a pull request. Donate on Open Collective. Chat with us in Discord — a maintainer is usually online. Stay up to date with Storybook news on Twitter and by signing up for our mailing list below.