[RFC] Official support for Svelte CSF

[JReinhold]

Summary

A majority of the Svelte community considers the Svelte CSF as implemented in @storybook/addon-svelte-csf a better way to write stories than with regular CSF. It’s closer to the syntax for writing regular Svelte components, it supports some features of Svelte that regular CSF doesn’t (such as slots and snippets), but it also comes with its own set of shortcomings.

This RFC proposes making Svelte CSF a first-class citizen of Storybook, including making it the official and default way to write stories for Svelte and documenting it in the docs.

As an open-source project, Storybook relies heavily on the community to build great things, and this is no exception. Given Storybook’s current roadmap, the core team can only participate in a guiding capacity, helping the community complete this effort with PR reviews and architectural guidance. This comes with its own set of challenges, but that’s the trade-off we have to make right now.

Problem Statement

Component Story Format (CSF) is a portable standard for capturing UI component examples. It is based on ECMAScript Modules (ESM), where the default export contains metadata about the component being documented, and each named export captures a key state of that component.

This is great for JSX-based frameworks because JSX can be embedded in a regular ESM file and thus you can do everything with JSX components in CSF. However the same isn’t true for template-based frameworks like Svelte and Vue - you can’t define a Svelte component directly in an ESM-file, it has to be its own .svelte file. This limits what you can do in CSF without defining multiples of Svelte components in separate files just for the sake of writing stories.

Svelte provides a set of APIs for mounting a component on the client - this is the API Storybook uses internally to render CSF-based stories. However this API is limited, you can’t do the same things with root Svelte components as you can with components within other components. In practice, this means that you can’t define slots in regular CSF, because there’s no way to pass a slot to a component when using Svelte’s mounting API, and thus there’s no way for Storybook to take a user’s slot and pass it to the component. The upcoming Svelte 5 introduces snippets as a replacement for slots, which have the same limitations.

@storybook/addon-svelte-csf solves a majority of these problems by allowing users to write stories with the Svelte language (we call this “Svelte CSF”), that are then compiled behind the scenes to CSF that Storybook can understand. This is great, and even with the current lack of visibility, it’s still used in the majority of Svelte-based Storybooks today.

However the addon comes with its own set of shortcomings, such as

• Lack of general documentation
• No explicit documentation mapping CSF features to the Svelte CSF equivalent, nor any known workarounds listed
• Some features are not supported fully, such as the test runner or Portable Stories

Most prominently, there’s no clear guide on when to use Svelte CSF vs CSF, leaving newcomers confused and in the dark.

We want to solve this by making Svelte CSF a default, first-class citizen of Storybook.

Non-goals

• This won’t solve templating languages in general in Storybook. This is specifically about Svelte.
• This won’t make Svelte CSF part of the CSF standard. We should attempt to make it possible for other CSF-based tools to support Svelte CSF, but we won’t make this part of regular CSF.
• This won’t support every single CSF feature 1-to-1 in Svelte CSF - at least not from day one. Some features don’t make sense in Svelte CSF, and some are harder to support than what can be achieved initially. We should however clearly identify which features are and aren’t supported.
• This won’t replace regular CSF for Svelte on a technical level. Storybook internals and tests rely heavily on regular CSF, and thus even the Svelte Storybook framework needs to support regular CSF still, although not necessarily in a publicly documented way.
• This won’t move the functionality of the addon into Storybook core, it will just ensure the addon is installed by default. We think it’s beneficial to keep the addon in its own repository with its own versioning. The Storybook monorepo can slow down development and the addon could benefit from higher velocity. This is not a final decision, so if anyone comes up with good counterarguments for why this should be baked into @storybook/svelte without the addon, we are open to discussing this.

Implementation

To solve these problems we propose the following changes:

1. Demo Project

The purpose of this project is to identify and describe the differences between regular CSF and Svelte CSF. Ideally, it should have a set of stories that uses all the features of Storybook with regular CSF, and a companion Svelte CSF version of all stories demonstrating how to do the same with Svelte CSF, or how and why this is not possible at the moment.

This project should be a separate repository in the Storybook GitHub org.

See the Deliverables section for a list of features to demonstrate.

It’s important to re-iterate that the purpose of this is not to show off how great Svelte CSF is, it’s to teach users and maintainers the differences and learn where it falls short. Hopefully, any shortcomings should be addressable in follow-up work improving Svelte CSF.

2. Document addon usage

We need to clearly document how this addon is a special case of Storybook, to not cause any confusion. I’m not sure what shape this takes, it might not be more than a few sentences or paragraph, or something else completely.

3. Convert all relevant code snippets in the docs to Svelte CSF

We have 200+ code snippets in the docs that shows CSF usage, that we should attempt to convert to Svelte CSF. This is a big lift and will happen over a longer period. This is also where the community can help out the most.

As an example, here’s how the first snippet in the Args doc could be converted:

<!-- Button.stories.svelte -->
<script context="module">
  import Button from './Button.svelte';

  export const meta = {
    component: Button
  }
</script>

<script>
  import { Story } from '@storybook/addon-svelte-csf';
</script>

<Story name="Primary" args={{ primary: true, label: 'Button' }}/>

We should incrementally add Svelte CSF code snippets as the main snippets, and remove snippets for regular CSF when they are not needed anymore. There might be specific features where we’ll intentionally keep regular CSF docs around because Svelte CSF doesn’t support them.

4. Install addon by default

This might already be covered by #27070

5. Automigration

If the documentation only documents Svelte CSF, we should write an automigration that

1. Explains this shift from CSF to Svelte CSF, possibly pointing to a relevant docs section or blog post
2. Offers to add the addon and modify the stories glob to match

It should only run on projects that don’t already have the addon installed.

6. Expose builder plugin

The Svelte CSF Addon relies on a builder plugin (Webpack and Vite) to compile Svelte CSF files to regular CSF files virtually. Storybook is starting to support non-Storybook environments like Portable Stories, and for that to work with Svelte CSF we’d need to expose this builder plugin from the package so it can be added to any configuration necessary.

7. Add stories and tests

To confidently provide support for Svelte CSF we’d want to have tests and stories in the monorepo that ensures we don’t introduce any regressions. While the addon does have some unit testing and stories, we should be able to expand on those (perhaps based on the demo project described above), but we also want to add stories and tests directly to the Svelte renderer in the monorepo.

Prior Art

No response

Deliverables

Important

If you want to contribute to any of this, just ask questions, start doing the work or open pull requests to the relevant repositories (see How to contribute). There’s no need to “reserve” a task or ask for being assigned to anything specifically before starting work on it. That system doesn’t work, often contributors reserving tasks ends up not doing them.

• Demo project - https://github.com/storybookjs/svelte-csf-demo
  • Scaffold repository with a README explaining the intent of the demo, how to use it and contribute @JReinhold
  • Create an example PR for a feature that the community can use as a template for each feature demo. @JReinhold
  • See the repos Overview for a list of deliverables.
• Install addon by default with storybook init CLI: Include @storybook/addon-svelte-csf when initializing new projects #27070
• Introductory documentation of Svelte CSF usage
• Convert docs code snippets to Svelte CSF (too many to list here)

Risks

1. Changing the whole underlying syntax is a disruptive change that can confuse existing users that don’t know about Svelte CSF.
2. Only a subset of the deliverables gets done for a long time, leaving the overall Svelte experience in a worse state with half-documented features or functionality that is not well tested.
3. The Storybook core team doesn’t have the bandwidth to guide and review a high influx of Svelte community work, leaving everyone frustrated and work never merged.

Unresolved Questions

• Do we still need to support Webpack in Svelte projects?

Over the past few years, the Svelte community has strongly favoured Vite over Webpack (See npmtrends). Adding official support for Svelte CSF is a major surface area increase, and it would be beneficial to keep that surface area under control by removing support for Svelte+Webpack. However, the Svelte core team still supports Webpack and we can’t ignore that we still have Svelte+Webpack users in Storybook - albeit a very small minority.

• Should we release a major version of the addon before starting on docs?

At the moment the community is trying to add support for Svelte 5 (here, and here) in the addon. Nothing is set in stone yet but it looks like the best way forward with that would be a breaking change to the addon, only supporting Svelte 5, and using snippets instead of slots for defining stories. Furthermore the new syntax for defining meta (old vs new) is better overall so we could consider removing support for the old syntax in that same major release.

If we did this, it would be best to do this before starting any docs work, given the syntax is slightly different. On the other hand, it would alienate all existing users that can’t/won’t upgrade to Svelte 5 for whatever reason. There isn’t a lot breaking in Svelte 5 and it still supports the Svelte 4 syntax, so requiring users to upgrade might not be the worst.

Alternatives considered / Abandoned Ideas

No response

[xeho91]

On the other hand, it would alienate all existing users that can’t/won’t upgrade to Svelte 5 for whatever reason. There isn’t a lot breaking in Svelte 5 and it still supports the Svelte 4 syntax, so requiring users to upgrade might not be the worst.

I'd like to put at ease regarding this matter, after what I found during my experiments.

While using an upgraded addon to support svelte@5, the custom (user's) components which have used svelte@4 features will still work. The addon's components (<Template /> & <Story />) got upgraded to v5, so basically what needs to be done is migrating from this:

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

to this:

<Story>
  {#snippet children(args)}
    <Button {...args} />
  {/snippet}
</Story>

A little bit more verbose, yeah, but the benefits are that args can have full TypeScript support, and with snippets there's more flexibility.

In theory it might be possible to keep the previous syntax for backwards compatibility, as Svelte considered to allow using snippets and slots together. I haven't explored this to be honest.

EDIT. Nope, I was wrong. I get the following error:

Cannot use `<slot>` syntax and `{@render ...}` tags in the same component. Migrate towards `{@render ...}` tags completely. [slot_snippet_conflict]

[xeho91]

I see about the component syntax, but I assume that the workspace's Svelte would still need to be upgraded to v5 right?

If you mean @storybook/svelte, I am not entirely sure, I don't think so. 🤔
I was able to make it work along with @storybook/addon-svelte-csf using svelte v5 and updated addon's components.

I haven't fully grasped yet the backward compatibility. As far I can tell from the quick glimpse. If we'd rewrite @storybook/svelte components to use svelte v5 with runes and snippets, then it shouldn't break the components passed down by user which haven't been upgraded yet.

[JReinhold]

What I mean is, the svelte dependency in the project's package.json would need to be ^5.0.0, and not ^4.0.0 - since svelte is just a peer dependency of the Storybook Svelte integration.

While Svelte 5 itself supports Svelte 4 syntax in general, there are some breaking changes with Svelte 5 that could block project's from upgrading. Hopefully it shouldn't be often though.

[xeho91]

I think maintainers of the Svelte can give a better answer than I do. 🙏
As far I can tell, we might not need to. But without any demo repository for reproduction and tests to see if anything breaks on @storybook/addon-svelte-csf (after upgrading to upcoming next major version) or @storybook/svelte side, I can only speculate.

[benmccann]

Yes, if you want to use snippets or any new features from Svelte 5 then the user's project will need Svelte 5 installed and Storybook will need to list it as a peerDependency. I think it should be fine to increase the peerDependency version in the next major release of Storybook. It is intended to be fairly straightforward for users to upgrade their projects to Svelte 5. There are some breaking changes, but they're intended to be fairly minimal such that most users won't hit most of them: https://svelte-5-preview.vercel.app/docs/breaking-changes

[JReinhold]

Great, that matches my mental model.

It is intended to be fairly straightforward for users to upgrade their projects to Svelte 5. There are some breaking changes, but they're intended to be fairly minimal such that most users won't hit most of them

I think this is the key point.