Storybook Addon Sass PostCSS

Description

The Storybook PostCSS addon can be used to run the PostCSS preprocessor with Sass support against your stories in Storybook.

:beginner: Use of Storybook v8 is strongly suggested with this addon since v0.2; The addon might be compatible with older Storybook versions as well but will no longer be extensively tested against.

Getting Started

Install this addon by adding the storybook-addon-sass-postcss dependency:

yarn add -D storybook-addon-sass-postcss

Then within .storybook/main.js:

module.exports = {
  addons: ['storybook-addon-sass-postcss'],
};

And create a PostCSS config in the base of your project, like postcss.config.js, that contains:

module.exports = {
  // Add your installed PostCSS plugins here:
  plugins: [
    // require('autoprefixer'),
    // require('postcss-color-rebeccapurple'),
  ],
};

PostCSS 8+

If your project requires you to be using PostCSS v8, you can replace the included PostCSS by passing postcssLoaderOptions to this addon.

First, you'll need to install PostCSS v8 as a dependency of your project:

yarn add -D postcss@^8

Then, you'll need to update your addons config. Within .storybook/main.js:

module.exports = {
  addons: [
-   'storybook-addon-sass-postcss',
+   {
+     name: 'storybook-addon-sass-postcss',
+     options: {
+       postcssLoaderOptions: {
+         implementation: require('postcss'),
+       },
+     },
+   },
  ]
}

When running Storybook, you'll see the version of PostCSS being used in the logs. For example:

info => Using PostCSS preset with postcss@8.2.4

Dart Sass

Similar to above, you can provide reference to your local Sass transpiler to invoke Dart Sass.

First, you'll need to install PostCSS v8 as a dependency of your project:

yarn add -D sass

Then, you'll need to update your addons config. Within .storybook/main.js:

module.exports = {
  addons: [
-   'storybook-addon-sass-postcss',
+   {
+     name: 'storybook-addon-sass-postcss',
+     options: {
+       sassLoaderOptions: {
+         implementation: require('sass'),
+       },
+     },
+   },
  ]
}

Sass Only

Be default, this plugin will try to transform both CSS and SASS modules. You can change this behaviour by passing optional argument rule.

module.exports = {
  addons: [
-   'storybook-addon-sass-postcss',
+   {
+     name: 'storybook-addon-sass-postcss',
+     options: {
+       rule: {
+         test: /\.(scss|sass)$/i,
+       },
+     },
+   },
  ]
}

Using with TailwindCSS

By default, Sass loading is done before PostCSS preprocessing. But this does not work well with TailwindCSS. As it relies on classnames and non-standard behaviours that are only exposed via PostCSS plugin. So to overcome this, Sass must be loaded after preprocessing has been done.

module.exports = {
  addons: [
-   'storybook-addon-sass-postcss',
+   {
+     name: 'storybook-addon-sass-postcss',
+     options: {
+       loadSassAfterPostCSS: true,
+     },
+   },
  ]
}

Loader Options

You can specify loader options for style-loader, css-loader, sass-loader and postcss-loader by passing options to this addon as styleLoaderOptions, cssLoaderOptions, sassLoaderOptions or postcssLoaderOptions respectively.