Docs FAQ
Storybook Docs

Frequently Asked Questions

Here are some answers to frequently asked questions. If you have a question, you can ask it by opening an issue on the Storybook Repository.

Error: No angular.json file found

Storybook can be set up for both single-project and multi-project Angular workspaces. To set up Storybook for a project, run npx storybook@latest init at the root of the workspace where the angular.json file is located. During initialization, the .storybook folder will be created and the angular.json file will be edited to add the Storybook configuration for the selected project. It's important to run the command at the root level to ensure that Storybook detects all projects correctly.

How can I opt-out of Angular Ivy?

In case you are having trouble with Angular Ivy you can deactivate it in your main.js:

export default {
  stories: [
    /* ... */
  ],
  addons: [
    /* ... */
  ],
  framework: {
    name: '@storybook/angular',
    options: {
      enableIvy: false,
    },
  },
};

How can I opt-out of Angular ngcc?

In case you postinstall ngcc, you can disable it:

export default {
  stories: [
    /* ... */
  ],
  addons: [
    /* ... */
  ],
  framework: {
    name: '@storybook/angular',
    options: {
      enableNgcc: false,
    },
  },
};

Please report any issues related to Ivy in our GitHub Issue Tracker as the support for View Engine will be dropped in a future release of Angular.

How can I run coverage tests with Create React App and leave out stories?

Create React App does not allow providing options to Jest in your package.json, however you can run jest with commandline arguments:

npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stories/*"]'

If you're using Yarn as a package manager, you'll need to adjust the command accordingly.

I see ReferenceError: React is not defined when using Storybook with Next.js

Next automatically defines React for all of your files via a babel plugin. In Storybook, you can solve this either by:

  1. Adding import React from 'react' to your component files.
  2. Adding a .babelrc that includes babel-plugin-react-require

How do I setup Storybook to share Webpack configuration with Next.js?

You can generally reuse Webpack rules by placing them in a file that is require()-ed from both your next.config.js and your .storybook/main.js files. For example:

export default {
  webpackFinal: async (baseConfig) => {
    const nextConfig = require('/path/to/next.config.js');
 
    // merge whatever from nextConfig into the webpack config storybook will use
    return { ...baseConfig, ...nextConfig };
  },
};

How do I fix module resolution in special environments?

In case you are using Yarn Plug-n-Play or your project is set up within a mono repository environment, you might run into issues with module resolution similar to this when running Storybook:

WARN   Failed to load preset: "@storybook/react-webpack5/preset"
Required package: @storybook/react-webpack5 (via "@storybook/react-webpack5/preset")

To fix this, you can wrap the package name inside your Storybook configuration file (i.e., .storybook/main.js|ts) as follows:

.storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
import path from 'path';
 
const getAbsolutePath = (packageName: string): any =>
  path.dirname(require.resolve(path.join(packageName, 'package.json')));
 
const config: StorybookConfig = {
  framework: {
    // Replace your-framework with the same one you've imported above.
    name: getAbsolutePath('@storybook/your-framework'),
    options: {},
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    //๐Ÿ‘‡ Use getAbsolutePath when referencing Storybook's addons and frameworks
    getAbsolutePath('@storybook/addon-essentials'),
  ],
};
 
export default config;

How do I setup React Fast Refresh with Storybook?

Fast refresh is an opt-in feature that can be used in Storybook React. There are two ways that you can enable it, go ahead and pick one:

  • You can set a FAST_REFRESH environment variable in your .env file:
FAST_REFRESH=true
  • Or you can set the following properties in your .storybook/main.js files:
export default {
  framework: {
    name: '@storybook/react-webpack5',
    options: {
      fastRefresh: true,
    },
  },
};

Fast Refresh only works in development mode with React 16.10 or higher.

How do I setup the new React Context Root API with Storybook?

If your installed React Version equals or is higher than 18.0.0, the new React Root API is automatically used and the newest React concurrent features can be used.

You can opt-out from the new React Root API by setting the following property in your .storybook/main.js file:

export default {
  framework: {
    name: '@storybook/react-webpack5',
    options: {
      legacyRootApi: true,
    },
  },
};

Why is there no addons channel?

A common error is that an addon tries to access the "channel", but the channel is not set. It can happen in a few different cases:

  1. You're trying to access addon channel (e.g., by calling setOptions) in a non-browser environment like Jest. You may need to add a channel mock:

    import { addons, mockChannel } from '@storybook/preview-api';
     
    addons.setChannel(mockChannel());
  2. In React Native, it's a special case documented in #1192

Why aren't Controls visible in the Canvas panel but visible in Docs?

If you're adding Storybook's dependencies manually, make sure you include the @storybook/addon-controls dependency in your project and reference it in your .storybook/main.js as follows:

// .storybook/main.js
 
export default {
  addons: ['@storybook/addon-controls'],
};

Why aren't the addons working in a composed Storybook?

Composition is a new feature that we released with version 6.0, and there are still some limitations to it.

For now, the addons you're using in a composed Storybook will not work.

We're working on overcoming this limitation, and soon you'll be able to use them as if you are working with a non-composed Storybook.

Can I have a Storybook with no local stories?

Storybook does not work unless you have at least one local story (or docs page) defined in your project. In this context, local means a .stories.* or .mdx file that is referenced in your project's .storybook/main.js config.

If you're in a Storybook composition scenario, where you have multiple Storybooks, and want to have an extra Storybook with no stories of its own, that serves as a "glue" for all the other Storybooks in a project for demo/documentation purposes, you can do the following steps:

Introduce a single .mdx docs page (addon-essentials or addon-docs required), that serves as an Introduction page, like so:

{/* Introduction.mdx */}
 
# Welcome
 
Some description here

And then refer to it in your Storybook config file:

// .storybook/main.js
const config = {
  // define at least one local story/page here
  stories: ['../Introduction.mdx'],
  // define composed Storybooks here
  refs: {
    firstProject: { title: 'First', url: 'some-url' },
    secondProject: { title: 'Second', url: 'other-url' },
  },
  // ...
};
export default config;

Which community addons are compatible with the latest version of Storybook?

Starting with Storybook version 6.0, we've introduced some great features aimed at streamlining your development workflow.

With this, we would like to point out that if you plan on using addons created by our fantastic community, you need to consider that some of those addons might be working with an outdated version of Storybook.

We're actively working to provide a better way to address this situation, but in the meantime, we would ask for a bit of caution on your end so that you don't run into unexpected problems. Let us know by creating an issue in the Storybook repo so that we can gather information and create a curated list with those addons to help not only you but the rest of the community.

Is it possible to browse the documentation for past versions of Storybook?

With the release of version 6.0, we updated our documentation as well. That doesn't mean that the old documentation was removed. We kept it to help you with your Storybook migration process. Use the content from the table below in conjunction with our migration guide.

We're only covering versions 5.3 and 5.0 as they were important milestones for Storybook. If you want to go back in time a little more, you'll have to check the specific release in the monorepo.

SectionPageCurrent LocationVersion 5.3 locationVersion 5.0 location
N/AWhy StorybookSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Get startedInstallSee current documentationSee versioned documentationSee versioned documentation
What's a storySee current documentationSee versioned documentation for your frameworkSee versioned documentation for your framework
Browse StoriesSee current documentationSee versioned documentation for your frameworkSee versioned documentation for your framework
SetupSee current documentationSee versioned documentation for your frameworkSee versioned documentation for your framework
Write storiesIntroductionSee current documentationSee versioned documentationSee versioned documentation
ParametersSee current documentationSee versioned documentationNon existing feature or undocumented
DecoratorsSee current documentationSee versioned documentationSee versioned documentation
Naming components and hierarchySee current documentationSee versioned documentationSee versioned documentation
Build pages and screensSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Stories for multiple componentsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Write docsAutodocsSee current documentationSee versioned addon documentationNon existing feature or undocumented
MDXSee current documentationSee versioned addon documentationNon existing feature or undocumented
Doc BlocksSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Preview and build docsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
TestingVisual testsSee current documentationSee versioned documentationSee versioned documentation
Accessibility testsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Interaction testsSee current documentationSee versioned documentationSee versioned documentation
Snapshot testsSee current documentationSee versioned documentationSee versioned documentation
Import stories in tests/Unit testsSee current documentationSee versioned documentationSee versioned documentation
Import stories in tests/End-to-end testingSee current documentationSee versioned documentationSee versioned documentation
SharingPublish StorybookSee current documentationSee versioned documentationSee versioned documentation
EmbedSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
CompositionSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Package CompositionSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Essential addonsControlsSee current documentationControls are specific to version 6.0 see Knobs versioned documentationControls are specific to version 6.0 see Knobs versioned documentation
ActionsSee current documentationSee addon versioned documentationSee addon versioned documentation
ViewportSee current documentationSee addon versioned documentationSee addon versioned documentation
BackgroundsSee current documentationSee addon versioned documentationSee addon versioned documentation
Toolbars and globalsSee current documentationSee versioned documentationNon existing feature or undocumented
ConfigureOverviewSee current documentationSee versioned documentationSee versioned documentation
Integration/FrameworksSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Integration/Framework support for frameworksSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Integration/CompilersSee current documentationSee versioned documentation hereSee versioned documentation here
Integration/TypescriptSee current documentationSee versioned documentationSee versioned documentation
Integration/Styling and CSSSee current documentationSee versioned documentationSee versioned documentation
Integration/Images and assetsSee current documentationSee versioned documentationSee versioned documentation
Story renderingSee current documentationSee versioned documentation here and hereSee versioned documentation here
Story LayoutSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
User Interface/Features and behaviorSee current documentationSee versioned documentationSee versioned documentation
User Interface/ThemingSee current documentationSee versioned documentationSee versioned documentation
User Interface/Sidebar & URLSSee current documentationSee versioned documentationSee versioned documentation
Environment variablesSee current documentationSee versioned documentationSee versioned documentation
BuildersIntroductionSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
ViteSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
WebpackSee current documentationSee versioned documentationSee versioned documentation
Builder APISee current documentationNon existing feature or undocumentedNon existing feature or undocumented
AddonsIntroductionSee current documentationSee versioned documentationSee versioned documentation
Install addonsSee current documentationSee versioned documentationSee versioned documentation
Writing AddonsSee current documentationSee versioned documentationSee versioned documentation
Writing PresetsSee current documentationSee versioned documentationNon existing feature or undocumented
Addons Knowledge BaseSee current documentationSee versioned documentationSee versioned documentation
Types of addonsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Addons APISee current documentationSee versioned documentationSee versioned documentation
API@storybook/blocks/ArgTypesSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/CanvasSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/ColorPaletteSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/ControlsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/DescriptionSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/IconGallerySee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/MarkdownSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/MetaSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/PrimarySee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/SourceSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/StoriesSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/StorySee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/SubtitleSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/TitleSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/TypesetSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/UnstyledSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
@storybook/blocks/useOfSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
Stories/Component Story FormatSee current documentationSee versioned documentationNon existing feature or undocumented
Stories/StoriesOF format (see note below)See current documentationSee versioned documentationNon existing feature or undocumented
ArgTypesSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/OverviewSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/frameworkSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/storiesSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/addonsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/babelSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/babelDefaultSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/buildSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/coreSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/docsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/envSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/featuresSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/indexersSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/logLevelSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/managerHeadSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/previewAnnotationsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/previewBodySee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/previewHeadSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/refsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/staticDirsSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/swcSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/typescriptSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/viteFinalSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/webpackFinalSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
main.js configuration/configSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
FrameworksSee current documentationNon existing feature or undocumentedNon existing feature or undocumented
CLI optionsSee current documentationSee versioned documentationSee versioned documentation

With the release of version 5.3, we've updated how you can write your stories more compactly and easily. It doesn't mean that the storiesOf format has been removed. For the time being, we're still supporting it, and we have documentation for it. But be advised that this is bound to change in the future.

What icons are available for my toolbar or my addon?

With the @storybook/components package, you get a set of icons that you can use to customize your UI. Use the table below as a reference while writing your addon or defining your Storybook global types. Go through this story to see how the icons look.

I see a "No Preview" error with a Storybook production build

If you're using the serve package to verify your production build of Storybook, you'll get that error. It relates to how serve handles rewrites. For instance, /iframe.html is rewritten into /iframe, and you'll get that error.

We recommend that you use http-server instead and use the following command to preview Storybook:

npx http-server storybook-static

Suppose you don't want to run the command above frequently. Add http-server as a development dependency and create a new script to preview your production build of Storybook.

Can I use Storybook with Vue 3?

Yes, with the release of version 6.2, Storybook now includes support for Vue 3. See the install page for instructions.

Why aren't my code blocks highlighted with Storybook MDX

Out of the box, Storybook provides syntax highlighting for a set of languages (e.g., Javascript, Markdown, CSS, HTML, Typescript, GraphQL) you can use with your code blocks. Currently, there's a known limitation when you try and register a custom language to get syntax highlighting. We're working on a fix for this And will update this section once it's available.

Why aren't my MDX 2 stories working in Storybook?

MDX 2 introduced some changes to how the code is rendered. For example, if you enabled it in your Storybook and you have the following code block:

<style>{`
  .class1 {
    ...
  }

  .class2 {
    ...
  }
`}</style>

You'll need to update it to make it compatible with MDX 2.

<style>
  {`
    .class1 {
      ...
    }

    .class2 {
      ...
    }
  `}
</style>

See the following issue for more information.

Why are my mocked GraphQL queries failing with Storybook's MSW addon?

If you're working with Vue 3, you'll need to install @vue/apollo-composable. With Svelte, you'll need to install @rollup/plugin-replace and update your rollup.config file to the following:

// rollup.config
 
// Boilerplate imports
 
import replace from '@rollup/plugin-replace';
const production = !process.env.ROLLUP_WATCH;
 
// Remainder rollup.config implementation
 
export default {
  input: 'src/main.js',
  output: {
    sourcemap: true,
    format: 'iife',
    name: 'app',
    file: 'public/build/bundle.js',
  },
  plugins: [
    // Other plugins
 
    // Configures the replace plugin to allow GraphQL Queries to work properly
    replace({
      'process.env.NODE_ENV': JSON.stringify('development'),
    }),
  ]
};

With Angular, the most common issue is the placement of the mockServiceWorker.js file. Use this example as a point of reference.

Can I use other GraphQL providers with Storybook's MSW addon?

Yes, check the addon's examples to learn how to integrate different providers.

Can I mock GraphQL mutations with Storybook's MSW addon?

No, currently, the MSW addon only has support for GraphQL queries. If you're interested in including this feature, open an issue in the MSW addon repository and follow up with the maintainer.

How can my code detect if it is running in Storybook?

You can do this by checking for the IS_STORYBOOK global variable, which will equal true when running in Storybook. The environment variable process.env.STORYBOOK is also set to true.

Why are my stories not showing up correctly when using certain characters?

Storybook allows you to use most characters while naming your stories. Still, specific characters (e.g., #) can lead to issues when Storybook generates the internal identifier for the story, leading to collisions and incorrectly outputting the correct story. We recommend using such characters sparsely.

Why are the TypeScript examples and documentation using as for type safety?

We are aware that the default Typescript story construct might seem outdated and could potentially introduce a less than ideal way of handling type safety and strictness and could be rewritten as such:

// Button.stories.ts|tsx
 
import React from 'react';
import type { ComponentStory, ComponentMeta } from '@storybook/react';
 
const StoryMeta: ComponentMeta<typeof Button> = {
  /* ๐Ÿ‘‡ The title prop is optional.
   * See https://storybook.js.org/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
};
 
export default meta;

Although valid, it introduces additional boilerplate code to the story definition. Instead, we are working towards implementing a safer mechanism based on what is currently being discussed in the following issue. Once the feature is released, we'll migrate our existing examples and documentation accordingly.

Why is Storybook's source loader returning undefined with curried functions?

This is a known issue with Storybook. If you're interested in getting it fixed, open an issue with a working reproduction so that it can be triaged and fixed in future releases.

Why are my args no longer displaying the default values?

Before version 6.3, unset args were set to the argTypes.defaultValue if specified or inferred from the component's properties (e.g., React's prop types, Angular inputs, Vue props). Starting with version 6.3, Storybook no longer infers default values but instead defines the arg's value as undefined when unset, allowing the framework to supply its default value.

If you are using argTypes.defaultValue to fix the above, you no longer need to, and you can safely remove it from your stories.

Additionally, suppose you were using argTypes.defaultValue or relying on inference to set a default value for an arg. In that case, you should define the arg's value at the component level instead:

// MyComponent.stories.js
 
export default {
  component: MyComponent,
  args: {
    //๐Ÿ‘‡ Defining the arg's value at the component level.
    text: 'Something',
  },
};

For Storybook's Docs, you can manually configure the displayed value by configuring the table.defaultValue setting:

// MyComponent.stories.js
 
export default {
  component: MyComponent,
  argTypes: {
    //๐Ÿ‘‡ Defining the arg's display value in docs.
    text: {
      table: { defaultValue: { summary: 'SomeType<T>' } },
    },
  },
};

Why isn't Storybook's test runner working?

There's an issue with Storybook's test runner and the latest version of Jest (i.e., version 28), which prevents it from running effectively. As a workaround, you can downgrade Jest to the previous stable version (i.e., version 27), and you'll be able to run it. See the following issue for more information.

How does Storybook handle environment variables?

Storybook has built-in support for environment variables. By default, environment variables are only available in Node.js code and are not available in the browser as some variables should be kept secret (e.g., API keys) and not exposed to anyone visiting the published Storybook.

To expose a variable, you must preface its name with STORYBOOK_. So STORYBOOK_API_URL will be available in browser code but API_KEY will not. Additionally you can also customize which variables are exposed by setting the env field in the .storybook/main.js file.

Variables are set when JavaScript is compiled so when the development server is started or you build your Storybook. Environment variable files should not be committed to Git as they often contain secrets which are not safe to add to Git. Instead, add .env.* to your .gitignore file and set up the environment variables manually on your hosting provider (e.g., GitHub).