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:

1yarn add -D storybook-addon-sass-postcss

Then within .storybook/main.js:

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

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

1module.exports = {
2  // Add your installed PostCSS plugins here:
3  plugins: [
4    // require('autoprefixer'),
5    // require('postcss-color-rebeccapurple'),
6  ],
7};

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:

1yarn add -D postcss@^8

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

1module.exports = {
2  addons: [
3-   'storybook-addon-sass-postcss',
4+   {
5+     name: 'storybook-addon-sass-postcss',
6+     options: {
7+       postcssLoaderOptions: {
8+         implementation: require('postcss'),
9+       },
10+     },
11+   },
12  ]
13}

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

1info => 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:

1yarn add -D sass

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

1module.exports = {
2  addons: [
3-   'storybook-addon-sass-postcss',
4+   {
5+     name: 'storybook-addon-sass-postcss',
6+     options: {
7+       sassLoaderOptions: {
8+         implementation: require('sass'),
9+       },
10+     },
11+   },
12  ]
13}

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.

1module.exports = {
2  addons: [
3-   'storybook-addon-sass-postcss',
4+   {
5+     name: 'storybook-addon-sass-postcss',
6+     options: {
7+       rule: {
8+         test: /\.(scss|sass)$/i,
9+       },
10+     },
11+   },
12  ]
13}

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.

1module.exports = {
2  addons: [
3-   'storybook-addon-sass-postcss',
4+   {
5+     name: 'storybook-addon-sass-postcss',
6+     options: {
7+       loadSassAfterPostCSS: true,
8+     },
9+   },
10  ]
11}

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.