Code snippets contributions

Add or update the code snippets in the documentation. This page outlines how the code snippets are structured.

Documented frameworks

Storybook maintains code snippets for a variety of frameworks. We try to keep them up to date as framework APIs evolve. But keeping track of every API change in every framework is tricky.

We welcome community contributions to the code snippets. Here's a matrix of the frameworks for which we have snippets. Help us add snippets for your favorite framework.

Snippet syntax

The code snippets referenced throughout the Storybook documentation are located in the docs/_snippets directory inside individual Markdown files, containing the supported frameworks, features and languages (i.e., JavaScript, MDX, TypeScript).

Example

The following code block demonstrates how to structure a code snippet in the Storybook documentation and the attributes you can use to provide additional context to the code snippet.

```ts filename="ButtonGroup.stories.ts" renderer="vue" language="ts" tabTitle="3"
import type { Meta, StoryObj } from '@storybook/vue3';
 
import ButtonGroup from './ButtonGroup.vue';
 
//👇 Imports the Button stories
import * as ButtonStories from './Button.stories';
 
const meta: Meta<typeof ButtonGroup> = {
 component: ButtonGroup,
};
 
export default meta;
type Story = StoryObj<typeof ButtonGroup>;
 
export const Pair: Story = {
  render: (args) => ({
 components: { ButtonGroup },
    setup() {
 return { args };
    },
 template: '<ButtonGroup v-bind="args" />',
  }),
 args: {
 buttons: [{ ...ButtonStories.Primary.args }, { ...ButtonStories.Secondary.args }],
 orientation: 'horizontal',
  },
};
``` 

Common attributes for code snippets

Following are the attributes you'll use most often in the Storybook documentation code snippets, as well as a brief explanation of each to help you understand the context in which they are used.

File name as title

Most code examples should include a file name so readers can understand which file they relate to and where to paste it into their project. For code examples, include the filename attribute wrapped with quotation marks to indicate the file name. This is not required if the example relates to a terminal command.

```ts filename="Button.stories.ts"
```

Language configuration

Use the language attribute to define the language to which the code snippet applies. The documentation uses this attribute to determine which variant to display (e.g., JavaScript, TypeScript, TypeScript 4.9, MDX).

```ts filename="Button.stories.ts" language="js|ts|ts-4-9|mdx"
```

Framework-specific code

Use the renderer attribute to indicate which of the supported frameworks the code snippet belongs to.

```ts filename="Button.stories.ts" language="ts" renderer="react|vue|angular|web-components|ember|html|svelte|preact|qwik|solid"
```

Alternatively, if you're documenting examples that apply to multiple frameworks, use the renderer attribute with the common value to indicate that the code snippet is framework-agnostic.

```ts filename="Button.stories.ts" language="ts" renderer="common"
```

Package manager configuration

Use the packageManager attribute to configure the package manager used in the example from the following options: npm, yarn, or pnpm.

```shell renderer="common" language="js" packageManager="npm|yarn|pnpm"
```

Working with multiple snippets

Use the tabTitle attribute to indicate the tab title in which the code snippet will be displayed. This attribute should only be used when multiple examples are in a single code snippet file.

```ts filename="YourConponent.stories.ts" language="ts" renderer="common" tabTitle="Story"
```
```ts filename=".storybook/preview.ts" language="ts" renderer="common" tabTitle="Storybook configuration"
```

Contributing code snippets

You can start contributing to the Storybook documentation by now that you're familiar with how the documentation is organized, the code snippet's structure, and available options. Assuming that you have already set up your local development environment and are ready to contribute, the following steps will guide you through contributing code snippets to the Storybook documentation.

Start by creating a new branch on your local Storybook monorepo with the following command:

git checkout -b code-snippets-for-framework

Browse the documentation and look for the code snippets you want to contribute. For example, on the setup page you should see the following:

{/* prettier-ignore-start */}
 
<CodeSnippets path="your-component.md" usesCsf3 />
 
{/* prettier-ignore-end */}

Open the file inside the docs/_snippets directory and adjust the content to match the code snippet you're willing to contribute. For example:

```ts filename="YourComponent.stories.ts" renderer="qwik" language="ts-4-9"
import type { Meta, StoryObj } from 'storybook-framework-qwik';
 
import type { YourComponentProps } from './YourComponent';
 
import { YourComponent } from './YourComponent';
 
//👇 This default export determines where your story goes in the story list
const meta = {
 component: YourComponent,
} satisfies Meta<YourComponentProps>;
 
export default meta;
type Story = StoryObj<YourComponentProps>;
 
export const FirstStory: Story = {
 args: {
 //👇 The args you need here will depend on your component
 },
};
```

Go through the rest of the documentation and repeat the process.

Preview your work

Before submitting your contribution, we encourage you to check your work against the Storybook website. Doing this prevents last-minute issues with the documentation and is also an excellent way for the maintainers to merge faster once you submit the pull request. However, failing to do so will lead one of the maintainers to notify you that your contribution has an issue.

Start by forking the Storybook website repository and cloning it locally.

git clone https://github.com/your-username/web.git

Navigate to the web directory and install the required dependencies.

npm install

We recommend that you generate a website build first to ensure you can preview your changes locally and verify that everything is working as expected. To do so, run the following command:

npm run build:frontpage

Run the sync-docs command to connect the documentation from the Storybook monorepo to the Storybook website. When prompted, provide the path to your local fork of the Storybook monorepo and the documentation version you're working on.

npm run sync-docs

Finally, open a new terminal window and run the dev command to start the Storybook website.

npm run dev

If all goes well, you should see the Storybook website running. Open a browser window to http://localhost:3000, click the Docs link to open the documentation, and select your framework from the dropdown.

Go through the documentation and check your work.

Submit your contribution

Once you have verified that your changes are working as expected, you're ready to create a "Pull Request". This will let the Storybook maintainers know you have some changes to propose. At this point, we can give you feedback and request changes. To help with the review process, we encourage you to add a clear title and description of your work.

Troubleshooting

Code snippets not displaying

If you're documenting an example that includes the packageManager attribute combined with another example, the documentation might not display the code snippets correctly. To avoid this, you can divide the examples into separate files and reference them in the documentation.

Learn more about contributing to Storybook

• RFC process for authoring feature requests
• Code for features and bug fixes
• Frameworks to get started with a new framework
• Documentation for documentation improvements, typos, and clarifications
• Examples for new snippets