RFC: Svelte 5 support

[JReinhold]

Addon Svelte CSF v5 RFC

In anticipation of the Svelte 5 release, we’ve re-imagined how the addon could improve by making use of the new features available in Svelte 5.

The purpose of this RFC is to share what we believe the future of the addon is and to collect feedback from the community. Everything described here is implemented in the latest prereleases of the addon, and can be used today. This doesn’t mean it’s set in stone, and we encourage anyone with feedback and ideas to come forward (otherwise why even have an RFC, right?). If there are significant or good suggestions, we’re very open to changing what we already have.

With the exception of the breaking changes listed below, the new version will be backwards compatible with the current API, under a legacyTemplate flag. The current API will be deprecated in favor of the new API described below and in the README. The new API heavily depends on snippets, so it’s not possible to migrate to the new API before upgrading to Svelte 5.

Please also check out the README on the next branch for a complete description of the new API.

To try out the new prereleases, upgrade your project to Svelte 5 and install the prereleases of this addon with npm install --save-dev @storybook/addon-svelte-csf@next.

Warning

Adding support for the legacy API isn’t done yet, it’s an ongoing process that will happen over the coming prereleases.

New API

1. <Meta> component and export meta replaced with defineMeta

Before:

<script>
	import { Meta } from "@storybook/addon-svelte-csf";
	
	import Button from "./Button.svelte";
</script>

<Meta title="Atoms/Button" component={Button} args={{ size: "medium" }} />

Or:

<script context="module">
	import { Story } from "@storybook/addon-svelte-csf";
	
	import Button from "./Button.svelte";
	
	export const meta = {
		title: "Atoms/Button",
		component: Button,
		args: {
			size: "medium",
		}.
	});
</script>

<Story name="Default" />

After:

A new defineMeta function has been introduced, to define the meta in any stories file:

<script context="module">
	import { defineMeta } from "@storybook/addon-svelte-csf";
	
	import Button from "./Button.svelte";
	
	const { Story } = defineMeta({
		title: "Atoms/Button",
		component: Button,
		args: {
			size: "medium",
		}.
	});
</script>

Difference:

 <script context="module">
-	import { Story } from "@storybook/addon-svelte-csf";
+	import { defineMeta } from "@storybook/addon-svelte-csf";
	
	import Button from "./Button.svelte";
	
- export const meta = {	
+ const { Story } = defineMeta({
		title: "Atoms/Button",
		component: Button,
		args: {
			size: "medium",
		}.
- };
+	});
 </script>
 
 <Story name="Default" />

Using this format allows for better type-safety, as the returned Story component has fully type-safe args.

This might not be too interesting for users that don’t care about type-safety. However we believe that only having one API to define the meta instead of a type-safe and non-typed API would cause more confusion than it would solve.

2. Story slots replaced with snippets

Before:

<Story name="Default" let:args>
  <Button {...args} />
</Story>

After:

<Story name="Default">
  {#snippet children(args, storyContext)}
     <Button {...args} />
  {/snippet}
</Story>

Difference:

- <Story name="Default" let:args>
+ <Story name="Default">
+   {#snippet children(args)}
       <Button {...args} />
+   {/snippet}
 </Story>

Using snippets also improves the type-safey of args. It also allows you to define multiple snippets and share them freely between stories however you like, by defining snippets top-level and passing them as the children prop instead of the default slot.

3. Template component replaced with template snippets

Svelte has deprecated support for slots in favour of snippets. They indeed give us more flexibility, and with this, we have three ways of setting a template for our <Story> components.

Tip

It’s also no longer required to define a template, stories without templates will just render the component with args becoming props.

Before:

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

<Story name="Default" args={{ size: "medium" }} />

After:

{#snippet template(args)}
  <Button {...args}>
    Click me
  </Button>
{/snippet}

<Story name="Default" args={{ size: "medium" }} children={template} />

The above can also be written as:

<Story name="Default" args={{ size: "medium" }}>
  {#snippet children(args)}
    <Button {...args}>
      Click me
    </Button>
  {/snippet}
</Story>

However, if you like to stop repeating yourself. We provide an alternative on how to set a template to every stories at once - setTemplate :

<script context="module">
  import { defineMeta, setTemplate } from "@storybook/addon-svelte-csf";
  
  const { Story } = defineMeta(...);
</script>

<script>
  setTemplate(sharedTemplate);
</script>

{#snippet sharedTemplate(args)}
  <Button {...args}>
    Click me
  </Button>
{/snippet}

<Story name="Small" args={{ size: "small" }} />

<Story name="Medium" args={{ size: "medium" }} />

<Story name="Large" args={{ size: "large" }} />

TypeScript support

By default, the following snippet from above example is untyped:

{#snippet sharedTemplate(args)}
  <!--                    ^ args is typeof 'any'-->
  <Button {...args}>
    Click me
  </Button>
{/snippet}

We’ve created two type helpers, Args and StoryContext, which you can import from this addon package:

 <!-- This is a "module" tag -->
- <script context="module">
+ <script context="module" lang="ts">
  import { setTemplate, type Args } from "@storybook/addon-svelte-csf";
 </script>

And then, we can use this type for out snippet:

- {#snippet sharedTemplate(args)}
+ {#snippet sharedTemplate(args: Args<typeof Story>)}
  <Button {...args}>
    Click me
  </Button>
{/snippet}

---

Breaking Changes

1. Dropped Webpack support

The Svelte community has been converging on Vite for years in favor of Webpack, something we’ve also been seeing in Storybook usage. As this addon relies more and more on transformations via builder plugins, we’ve decided that now is a good time to drop support for Webpack and only support Vite-based Storybooks. This is a simple matter of prioritising time, only supporting Vite means we can focus more of our effort on improving the experience with new features and bug fixes.

2. <Meta> component removed

The <Meta> component has been removed, after being deprecated for 10 months. You can migrate to the current API with export const meta or the new defineMeta() API described above.

3. <Story> prop autodocs removed

Before:

<Story name="Default" autodocs />

After:

<Story name="Default" tags={['autodocs']} />

This aligns better with regular CSF, making it easier to follow the complete Storybook docs as reference.

4. <Story> prop source has been removed

Before:

<Story name="Default" source />
<!-- or -->
<Story name="Default" source={"<Button {...args}>Click me</Button>"} />

After:

<Story name="Default" />

We’ve been able to improve the default source generation a lot because of the new snippets syntax, and therefore the source prop (as a boolean) shouldn’t be necessary anymore. You can still customize the generated source with the built-in parameters parameters.docs.source.code and parameters.docs.source.transform . The string-based form of the source prop was in fact just a shorthand for the code parameter - streamlining this means fewer APIs to learn.

[bhvngt]

Thanks a ton @JReinhold for all the improvements that have been put into this addon. I have been playing around with a toy project and till now its working pretty well.

When I was using this with test-runner, I think its still runs only with index-json flag. Which is totally fine. However, when I run this with --watchAll, changes made in .stories.svelte or my component files are not detected. Is this an expected behaviour or should I create a bug for this issue

[JReinhold]

Thank you for your kind words.

Unfortunately index.json mode is not compatible with watch mode as stated in the bottom of the index.json mode docs - and unfortunately index.json is the only way to use the test runner with Svelte CSF. There's no easy solution right now to any of those two things.