Mastering SvelteKit Component Documentation: A Guide to using Storybook
Tags: storybook, tailwindcss, typescript, svelte
Published: 2023-05-30 01:17:03

---
title: Mastering SvelteKit Component Documentation: A Guide to using Storybook
published: true
description: 
tags: storybook, tailwindcss, typescript, svelte
cover_image: https://res.cloudinary.com/morelmiles/image/upload/v1685402159/Group_33633_sxgdz4.png
# published_at: 2023-05-29 23:11 +0000
---

## 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](https://tailwindcss.com/docs/guides/sveltekit)

## Getting started

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

_You could go straight to the project's [respository here](https://github.com/morelmiles/svelte-storybook)_

```bash
$ npm create svelte@latest storybook-tutorial
```

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

![image of terminal](https://res.cloudinary.com/morelmiles/image/upload/v1685264128/Screenshot_from_2023-05-28_11-54-36_etwjib.png)

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

```bash
$ npx storybook init
```

Once the installation is done, run the command below.

```bash
$ npm run storybook
```

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

![image of the storybook web interface](https://res.cloudinary.com/morelmiles/image/upload/v1685265250/Screenshot_from_2023-05-28_12-13-39_rnacy4.png)

## 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:

![project structure](https://res.cloudinary.com/morelmiles/image/upload/v1685335478/Screenshot_from_2023-05-29_07-43-54_aiyqtw.png)

- `.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](https://github.com/morelmiles/svelte-storybook)

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

```markdown.
├── 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.

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

2. 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:

```svelte
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

```svelte
<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:

```svelte
<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..
![storybook](https://res.cloudinary.com/morelmiles/image/upload/v1685404307/Screenshot_from_2023-05-30_02-51-21_v6wcbl.png)

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/](https://sveltekit-storybook.netlify.app/)

![web page](https://res.cloudinary.com/morelmiles/image/upload/v1685380324/Screenshot_from_2023-05-29_20-10-53_hcsk18.png)

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](https://github.com/morelmiles/svelte-storybook)

Happy coding!

PS: This article first appeared on my personal blog [https://luigimorel.co](https://luigimorel.co)