Repository files navigation

This Storybook addon allows you to write Storybook stories using the Svelte language instead of ESM that regular CSF is based on.

npx storybook@latest add @storybook/addon-svelte-csf

Using the Svelte language makes it easier to write stories for composed components that rely on snippets or slots, which aren't easily re-created outside of Svelte files.

The easiest way to install the addon is withstorybook add:

npx storybook@latest add @storybook/addon-svelte-csf

You can also add the addon manually. First, install the package:

npm install --save-dev @storybook/addon-svelte-csf

Then modify yourmain.ts Storybook configuration to include the addon and include*.stories.svelte files:

export default {-  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx|svelte)'],  addons: [+    '@storybook/addon-svelte-csf',    ...  ],  ...}

Restart your Storybook server for the changes to take effect.

Theexamples directory contains examples describing each feature of the addon. TheButton.stories.svelte example is a good one to get started with.The Storybook with all the examples is published on Chromatic here.

Svelte CSF stories files must always have the.stories.svelte extension.

All stories files must have a "meta" (aka. "default export") defined, and its structure follows what's described inthe official docs on the subject. To define the meta in Svelte CSF, call thedefineMeta functionwithin the module context, with the meta properties you want:

<scriptmodule>//    👆 notice the module context, defineMeta does not work in a regular <script> tag - instanceimport {defineMeta }from'@storybook/addon-svelte-csf';importMyComponentfrom'./MyComponent.svelte';//      👇 Get the Story component from the return valueconst {Story }=defineMeta({    title:'Path/To/MyComponent',    component: MyComponent,    decorators: [/* ...*/    ],    parameters: {/* ...*/    },  });</script>

defineMeta returns an object with aStory component (seeDefining stories below) that you must destructure out to use.

To define stories, you use theStory component returned from thedefineMeta function. Depending on what you want the story to contain,there are multiple ways to use theStory component. Common for all the use case is that all properties ofa regular CSF story are passed as props to theStory component, with the exception of therender function, which does not have any effect in Svelte CSF.

All story requires either thename prop orexportName prop.

If your component only accepts props and doesn't require snippets or slots, you can use the simple form of defining stories, only using args:

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

This will render the component defined in the meta, with the args passed as props.

If your component needs children, you can pass them in directly to the story, and they will be forwarded to your component:

<Storyname="With Children">I will be the child of the component from defineMeta</Story>

If you need more customization of the story, like composing components or defining snippets, you can set theasChild prop on the Story. Instead of forwarding the children to your component, it will instead use the children directly as the story output. This allows you to write whatever component structure you desire:

<Storyname="Composed"asChild>  <MyComponent>    <AChildlabel="Hello world!" />  </MyComponent></Story>

If you need composition/snippets but also want a dynamic story that reacts to args or the story context, you can define atemplate snippet in theStory component:

<Storyname="Simple Template"args={{simpleChild:true }}>  {#snippettemplate(args)}    <MyComponent {...args}>Component with args</MyComponent>  {/snippet}</Story>

Often your stories are very similar and their only differences are args or play-functions. In this case it can be cumbersome to define the sametemplate snippet over and over again. You can share snippets by defining them at the top-level and passing them as props toStory:

{#snippettemplate(args)}  <MyComponent {...args}>    {#ifargs.simpleChild}      <AChilddata={args.childProps} />    {:else}      <ComplexChildAdata={args.childProps} />      <ComplexChildBdata={args.childProps} />    {/if}  </MyComponent>{/snippet}<Storyname="Simple Template"args={{simpleChild:true }} {template} /><Storyname="Complex Template"args={{simpleChild:false }} {template} />

You can also use this pattern to define multiple templates and share the different templates among different stories.

If you only need a single template that you want to share, it can be tedious to include{template} in eachStory component. Like in th example below:

<Storyname="Primary"args={{variant:'primary' }} {template} /><Storyname="Secondary"args={{variant:'secondary' }} {template} /><Storyname="Tertiary"args={{variant:'tertiary' }} {template} /><!-- ... more ... --><Storyname="Denary"args={{variant:'denary' }} {template} />

Similar to regular CSF, you can define a meta-levelrender-function, by referencing your default snippet in therender property of yourdefineMeta call:

<scriptmodule>import {defineMeta }from'@storybook/addon-svelte-csf';importMyComponentfrom'./MyComponent.svelte';const {Story }=defineMeta({    render: template,//      👆 the name of the snippet as defined below (can be any name)  });</script>{#snippettemplate(args)}  <MyComponent {...args}>    {#ifargs.simpleChild}      <AChilddata={args.childProps} />    {:else}      <ComplexChildAdata={args.childProps} />      <ComplexChildBdata={args.childProps} />    {/if}  </MyComponent>{/snippet}<Storyname="Simple Children"args={{simpleChild:true }} /><Storyname="Complex Children"args={{simpleChild:false }} />

Stories can still override this default snippet using any of the methods for defining story-level content.

Behind-the-scenes, each<Story /> definition is compiled to a variable export likeexport const MyStory = ...;. In most cases you don't have to care about this detail, however sometimes naming conflicts can arise from this. The variable names are simplifications of the story names - to make them valid JavaScript variables.

This can cause conflicts, eg. two stories with the names"my story!" and"My Story" will both be simplified toMyStory.

You can explicitly define the variable name of any story by passing theexportName prop:

<StoryexportName="MyStory1"name="my story!" /><StoryexportName="MyStory2"name="My Story" />

At least one of thename orexportName props must be passed to theStory component - passing both is also valid.

If for some reason you need to access theStory context(e.g. for mocking) while rendering the story, then<Story />'s attributetemplate snippet provides an optional second argument.

<Storyname="Default">  {#snippettemplate(args,context)}<!--                    👆 use the optional second argument to access Story context -->     <MyComponent {...args}>  {/snippet}</Story>

Story template snippets can be type-safe when necessary. The type of the args are inferred from thecomponent orrender property passed todefineMeta.

If you're just rendering the component directly without a custom template, you can use Svelte'sComponentProps type andStoryContext from the addon to make your template snippet type-safe:

<scriptmodulelang="ts">import {defineMeta,typeStoryContext }from'@storybook/addon-svelte-csf';import {typeComponentProps }from'svelte';importMyComponentfrom'./MyComponent.svelte';const { Story }=defineMeta({    component:MyComponent,  });typeArgs=ComponentProps<MyComponent>;</script>{#snippettemplate(args:Args,context:StoryContext<typeofLayout>)}  <MyComponent {...args} />{/snippet}

If you use therender-property to define a custom template that might use custom args, the args will be inferred from the types of the snippet passed torender. This is especially useful when you're converting primitive args to snippets:

<scriptmodulelang="ts">import {defineMeta,typeStoryContext }from'@storybook/addon-svelte-csf';import {typeComponentProps }from'svelte';importMyComponentfrom'./MyComponent.svelte';const { Story }=defineMeta({    component:MyComponent,    render:template,// 👈 args will be inferred from this, which is the Args type below    argTypes: {      children: {        control:'text',      },      footer: {        control:'text',      },    },  });typeArgs=Omit<ComponentProps<MyComponent>,'children'|'footer'>& {    children:string;    footer?:string;  };// OR use the Merge helper from the 'type-fest' package:typeArgs=Merge<ComponentProps<MyComponent>,    {      children:string;      footer?:string;    }  >;</script><!--                👇 you need to omit 'children' from args to satisfy Svelte's constraints -->{#snippettemplate({children,...args }:Args,context:StoryContext<typeofMyComponent>)}  <MyComponent {...args}>    {children}    {#snippetfooter()}      {args.footer}    {/snippet}  </MyComponent>{/snippet}

SeetheTypes.stories.svelte examples on how to use complex types properly.

Version 5 of the addon changes the API from v4 in key areas, as described above. However a feature flag has been introduced to maintain support for the<Template>-based legacy API as it was prior to v5.

To enable supoprt for the legacy API, make the following change to your main Storybook config:

export default {  addons: [-    '@storybook/addon-svelte-csf',+    {+      name: '@storybook/addon-svelte-csf',+      options: {+         legacyTemplate: true+    },    ...  ],  ...}

This can make the overall experience slower, because it adds more transformation steps on top of the existing ones. It should only be used temporarily while migrating to the new API. It's highly likely that the legacy support will be dropped in future major versions of the addon.

The legacy support is not bullet-proof, and it might not work in all scenarios that previously worked. If you're experiencing issues or getting errors after upgrading to v5, try migrating the problematic stories files to the modern API.

Version 5 and up of this addon requiresat least:

npm install --save-dev @storybook/addon-svelte-csf@^4

Version 4 of this addon requiresat least:

• Storybook v7
• Svelte v4
• Vite v4 (if using Vite)
• @sveltejs/vite-plugin-svelte v2 (if using Vite)

npm install --save-dev @storybook/addon-svelte-csf@^3

Version 3 of this addon requiresat least:

• Storybook v7
• Svelte v3

npm install --save-dev @storybook/addon-svelte-csf@^2

If you're using Storybook between v6.4.20 and v7.0.0, you should use version^2.0.0 of this addon.

This project usespnpm for dependency management.

1. Install dependencies withpnpm install
2. Concurrently start the compilation and the internal Storybook withpnpm start.
3. Restarting the internal Storybook is often needed for changes to take effect.