Mastering SvelteKit Component Documentation: A Guide to using Storybook

What is Storybook?

Storybook positions itself as a frontend workshop for building user interface (UI) components and pages in isolation. Storybook can be used for documentation, testing and documentation.

The core principle of Storybook revolves around utilizing "stories" as a means to effectively document components.

Stories are a declarative syntax for supplying props and mock data to simulate component variations. Each component can have multiple stories. Each story allows you to demonstrate a specific variation of that component to verify appearance and behavior.

Prerequisites

This tutorial covers how to setup component documentation using Storybook and Svelte. I'll assume you know the following:

• How to create a Svelte project
• How to use install packages using NPM or Yarn
• Experience with creating user interfaces
• How to install and use Tailwindcss in SvelteKit. Here's the link to the documentation

Getting started

To get started, create a new SvelteKit project in your preferred dicrectory.

You could go straight to the project's respository here

$ npm create svelte@latest storybook-tutorial

Follow the prompts displayed in your terminal. You should see something like this:

You now have a SvelteKit project to work with.
Let's now install Storybook.

$ npx storybook init

Once the installation is done, run the command below.

$ npm run storybook

At this point, a web interface (like the one below) should open up on port 6006 in your browser.

Documenting our components

If you check the sidebar of the interface that's popped up in your browser, there is already example documentation for the Button, Header and Page components (see image above)

Your project folder should be looking like this:

• .storybook contains your Storybook configuration
• src holds your Svelte project files

Let's delete some of the the files that we do not need.

Delete the stories folder and all it's contents. Go ahead and create a components folder inside of the lib directory.

Inside the components folder create 3 folders, namely:

• Buttons
• Icons, and
• Modals

Through out this tutorial, we will focus on documenting Button component. The documentation for the Modals and Icons can be found in this tutorial's repository

Below is how your src directory should be looking like by now:

├── app.d.ts
├── app.html
├── lib
│ └── components
│ ├── Buttons
│ │ ├── Button.stories.svelte
│ │ └── Button.svelte
│ ├── Footer.svelte
│ ├── Hero.svelte
│ ├── Icons
│ │ ├── Icon.stories.svelte
│ │ └── Icon.svelte
│ ├── Modals
│ │ ├── Modal.stories.svelte
│ │ └── Modal.svelte
│ ├── Navbar.svelte
│ └── Services.svelte
├── routes
│ ├── +layout.svelte
│ ├── +page.svelte
│ └── +page.ts
└── styles
└── app.css

Documenting the Button component

1. Install the @storybook/addon-svelte-csf package which will allows us to write the stories in Svelte syntax and compiles it to Storybook's CSF syntax.

$ npm install -D @storybook/addon-svelte-csf

1. Let's go ahead and change our .storybook/main.ts file so that Storybook can pick up our .svelte files. Also, we have added the @storybook/addon-svelte-csf to the addons array. This is how it should look like:

import type { StorybookConfig } from '@storybook/sveltekit'
 const config: StorybookConfig = {
  +stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx|svelte)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-svelte-csf',
  ],
  framework: {
    name: '@storybook/sveltekit',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
}
export default config

Now that we are done with configurations, let's jump straight into defining how our Button component looks like:

Here's a sample user story for our buttons

A button component with four sizes (small, medium, large, extra-large) for flexible design and consistent user experience across devices.

Go to the Button.svelte file and paste this code

<script lang="ts">
    export let href: string = '';

    // Button sizes
    /**
     * @type {'small' | 'medium' | 'large' | 'extra-large' }
     */

    export let type: string = 'small';

    let buttonType: string;

    if (type === 'small') {
        buttonType = 'bg-slate-500 text-xs px-5 hover:bg-slate-500/90';
    } else if (type === 'medium') {
        buttonType = ' bg-red-500 px-7 text-sm hover:bg-red-500/90';
    } else if (type === 'large') {
        buttonType = ' bg-teal-500  px-9 text-base hover:bg-teal-500/90';
    } else {
        buttonType = ' bg-violet-500 text-lg px-12 hover:bg-violet-500/90';
    }
</script>

<a class={` btn ${buttonType}`} {href} target="_blank" rel="noreferrer">
    <div class="flex items-center gap-2">
        <slot />
    </div>
</a>

Let's go ahead and create our Storybook stories for the Button component. Go to the Button.stories.svelte file you created earlier in the lib/components/Buttons directory.
Copy and paste the code below:

<script lang="ts">
    import { Meta, Story } from '@storybook/addon-svelte-csf';

    import Button from './Button.svelte';
</script>

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

<!-- Small -->
<Story name="Small">
    <Button href="https://google.com">Small Button</Button>
</Story>

<!-- medium -->
<Story name="Medium">
    <Button type="medium" href="https://google.com">Medium Button</Button>
</Story>

<!-- large-->
<Story name="Large">
    <Button type="large" href="https://google.com">Large Button</Button>
</Story>

<!-- extra-large-->
<Story name="Extra Large">
    <Button type="extra-large" href="https://google.com">Extra Large Button</Button>
</Story>

Restart your Storybook server that's running on port 6006.

By now you should be able to see your Button component documentation showing in the web interface. This is how it should look like at this point..

And that's it! We have successfully documented our Button components that can be used in our SPAs.
Here's a look at our Button component being used in a web page. Visit this link: https://sveltekit-storybook.netlify.app/

If you'd like to look at the documentation for rest of the components (Modals and Icons), please take a look the the tutorial's repository here

Happy coding!

PS: This article first appeared on my personal blog https://luigimorel.co