# Configure for Storybook

To configure Rslib for Storybook, execute the following steps 👇

pnpm add -D @workleap/rslib-configs @rslib/core @rsbuild/core storybook-react-rsbuild storybook-addon-rslib

yarn add -D @workleap/rslib-configs @rslib/core @rsbuild/core storybook-react-rsbuild storybook-addon-rslib

npm install -D @workleap/rslib-configs @rslib/core @rsbuild/core storybook-react-rsbuild storybook-addon-rslib

Rslib Storybook integration is an addon that derives an Rsbuild configuration from an existing Rslib configuration file. This addon automatically reads the Rslib configuration and applies it to Storybook's Rsbuild framework, ensuring that the configuration is unified.

As a result, configuring a Storybook instance for Rslib is very similar to configuring a Storybook instance for Rsbuild.

First, create a configuration file named rslib.config.ts under the .storybook folder:

storybook
├── .storybook
├──── main.ts
├──── preview.tsx
├──── rslib.config.ts
├── package.json

Then, open the newly created file and export the Rslib configuration by using the defineStorybookConfig(options) function:

import { defineStorybookConfig } from "@workleap/rslib-configs";

export default defineStorybookConfig();

Finally, open the .storybook/main.ts file and set storybook-react-rsbuild as the framework to use and storybook-addon-rslib as an addon:

import type { StorybookConfig } from "storybook-react-rsbuild";

const storybookConfig: StorybookConfig = {
    framework: "storybook-react-rsbuild",
    addons: ["storybook-addon-rslib"],
    stories: ["../../src/**/*.stories.(tsx|mdx)"]
};

export default storybookConfig;

The defineStorybookConfig(options) function can be used as shown in the previous example, however, if you wish to customize the default configuration, the function also accept a few predefined options to help with that 👇

• Type: An array of Rsbuild plugin instances
• Default: []

Append the provided Rsbuild plugins to the configuration.

import { defineStorybookConfig } from "@workleap/rslib-configs";
import { pluginAssetsRetry } from "@rsbuild/plugin-assets-retry";

export default defineStorybookConfig({
    plugins: [pluginAssetsRetry()]
});

• Type: false or an object literal accepting any output.sourceMap options.
• Default: { js: "cheap-module-source-map", css: true }

Whether or not to generate source map. To disable source map, set the option to false.

import { defineStorybookConfig } from "@workleap/rslib-configs";

export default defineStorybookConfig({
    sourceMap: false
});

To customize the source map configuration, provide an object literal.

import { defineStorybookConfig } from "@workleap/rslib-configs";

export default defineStorybookConfig({
    sourceMap: {
        css: false
    }
});

• Type: false or (defaultOptions: PluginReactOptions) => PluginReactOptions
• Default: defaultOptions => defaultOptions

Whether or not to transform React code. To disable React code transformation, set the option to false.

import { defineStorybookConfig } from "@workleap/rslib-configs";

export default defineStorybookConfig({
    react: false
});

To customize plugin-react, provide a function to extend the default options.

import { defineStorybookConfig } from "@workleap/rslib-configs";

export default defineStorybookConfig({
    react: defaultOptions => {
        return {
            ...defaultOptions,
            swcReactOptions: {
                ...(defaultOptions.swcReactOptions ?? {}),
                runtime: "classic"
            }
        };
    }
});

• Type: false or (defaultOptions: PluginSvgrOptions) => PluginSvgrOptions
• Default: defaultOptions => defaultOptions

Whether or not to handle .svg files with plugin-svgr. When the option is set to false, the .svg files will be handled by the asset/resource rule.

import { defineStorybookConfig } from "@workleap/rslib-configs";

export default defineStorybookConfig({
    svgr: false
});

To customize plugin-svgr, provide a function extending the default options.

import { defineStorybookConfig } from "@workleap/rslib-configs";

export default defineStorybookConfig({
    svgr: defaultOptions => {
        return {
            svgrOptions: {
                ...(defaultOptions.svgrOptions ?? {}),
                ref: true
            }
            ...defaultOptions,

        }
    }
});

When an SVG asset in referenced in TypeScript code, TypeScript may prompt that the module is missing a type definition:

TS2307: Cannot find module './logo.svg' or its corresponding type declarations.

To fix this, add a type declaration for the SVG assets, by creating a src/env.d.ts file, and add the type declaration.

declare module '*.svg' {
  export const ReactComponent: React.FunctionComponent<
    React.SVGProps<SVGSVGElement>
  >;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

For additional information, refer to the plugin documentation.

By default, plugin-svgr is configured to support named import for ReactComponent:

import { ReactComponent as Logo } from "./logo.svg";

export const App = () => <Logo />;

The predefined options are useful to quickly customize the default Storybook configuration of @workleap/rslib-configs, but only covers a subset of an Rslib configuration. If you need full control over the configuration, you can provide configuration transformer functions through the transformers option of the defineStorybookConfig function. Remember, no locked in ❤️✌️.

To view the default Storybook configuration of @workleap/rslib-configs, have a look at the storybook.ts configuration file on GitHub.

• Type: ((config: RslibConfig, context: RslibConfigTransformerContext) => RslibConfig)[]
• Default: []

transformer(config: RslibConfig, context: RslibConfigTransformerContext) => RslibConfig

import { defineStorybookConfig, type RslibConfig, type RslibConfigTransformer } from "@workleap/rslib-configs";

const useInlineStylesTransformer: RslibConfigTransformer = (config: RslibConfig) => {
    config.output = {
        ...(config.ouput ?? {}),
        inlineStyles: true
    };

    return config;
};

export default defineStorybookConfig({
    transformers: [useInlineStylesTransformer]
});

Generic transformers can use the context parameter to gather additional information about their execution context, like the environment they are operating in.

import type { RslibConfig, RslibConfigTransformer } from "@workleap/rslib-configs";

export const transformer: RslibConfigTransformer = (config: RslibConfig) => {
    if (context.environment === "storybook") {
        config.output = {
            ...(config.ouput ?? {}),
            inlineStyles: true
        };
    }

    return config;
}

• environment: "dev" | "build" | "storybook"

Add the following scripts to the project package.json file:

{
    "dev": "storybook dev -p 6006",
    "build": "storybook build"
}

To test the new Rslib configuration, open a terminal at the root of the project and execute the CLI scripts added earlier. Either the Storybook development server should start without outputting any error in the terminal or the Storybook application bundle files should be available in the /storybook-static folder (or any other folder you configured).