Skip to main content

storybook-addon

Storybook addon for tramvai apps

Installation​

You need to install @tramvai/storybook-addon:

npm install @tramvai/storybook-addon

And connect addon in the storybook configuration file:

.storybook/main.js
module.exports = {
  addons: ['@tramvai/storybook-addon'],
};

Features​

  • Providers for DI container
  • Providers for router
  • Providers for react-query
  • Page actions support
  • tramvai babel configuration
  • tramvai postcss configuration

Webpack plugin only​

In some cases, adding the addon may be difficult due to conflicts.

In such situations, you can use only the webpack plugin from the addon:

// .storybook/main.js
import { webpackFinal } from '@tramvai/storybook-addon';

export default {
  webpackFinal,
};

Or if you have your own webpack overrides:

// .storybook/main.js
import { webpackFinal as tramvaiWebpackFinal } from '@tramvai/storybook-addon';

export default {
  webpackFinal: async (config) => {
    const webpackConfig = await tramvaiWebpackFinal(config);

    // Do something with config
    webpackConfig.optimization = {
      minimize: false,
    };

    return webpackConfig;
  },
};

We strongly recommend to use at least tramvai webpack plugin in storybook tests.

Webpack build optimization​

We recommend configuring selective transpilation of node_modules for the webpack build that Tramvai performs by default. To do this, use the include option in the addon/webpack config options.

This significantly speeds up the build (up to 2x with Babel).

By default, the value only-modern is used, which, based on certain heuristics, tries to apply transpilation only to modern dependencies.

We recommend using the value none to completely skip node_modules transpilation:

const webpackConfig = await tramvaiWebpackFinal(config, { include: 'none' });

Also, for the storybook addon:

export default = {
  addons: {
    name: '@tramvai/storybook-addon',
    options: {
      include: 'none'
    },
  }
}

If you encounter issues, specify the list of dependencies to transpile as an array:

const webpackConfig = await tramvaiWebpackFinal(config, { include: ['@tramvai/module-dev-tools'] });

Babel configuration​

You can also use only the Babel config from the Tramvai plugin, but in that case you must implement all the missing build machinery for Tramvai by yourself:

import { babel } from '@tramvai/storybook-addon';

export default {
  webpackFinal: (config) => {
    // Find babel rule you want to update
    const babelRule = config.module.rules.find(({ use }) =>
      use?.find(({ loader }) => loader.includes('babel-loader'))
    );

    const tramvaiBabelOptions = babel(config);
    Object.assign(babelRule.use[0].options, tramvaiBabelOptions);

    return config;
  },
};

How to​

Access to DI container​

import { LOGGER_TOKEN } from '@tramvai/tokens-common';

export const Page = () => {
  const logger = useDi(LOGGER_TOKEN);

  logger.info('render');

  return <h1>Page</h1>;
};

Router hooks and components​

import { Link, useUrl } from '@tramvai/module-router';

export const Page = () => {
  const url = useUrl();

  return (
    <>
      <h1>Page at {url.pathname}</h1>
      <p>
        <Link url="/third/">to third page</Link>
      </p>
    </>
  );
};

React Query​

import { createQuery, useQuery } from '@tramvai/react-query';

const query = createQuery({
  key: 'base',
  fn: async () => {
    return { foo: 'bar' };
  },
});

export const Page = () => {
  const { data, isLoading } = useQuery(query);

  return (
    <>
      <h1>Page</h1>
      <p>{isLoading ? 'Loading...' : data.foo}</p>
    </>
  );
};

Page actions running​

import { declareAction } from '@tramvai/core';

const serverAction = declareAction({
  name: 'server-action',
  fn() {
    console.log('server action');
  },
  conditions: {
    onlyServer: true,
  },
});

const browserAction = declareAction({
  name: 'browser-action',
  fn() {
    console.log('browser action');
  },
  conditions: {
    onlyBrowser: true,
  },
});

export const Page = () => {
  return <h1>Page</h1>;
};

Page.actions = [serverAction, browserAction];

Http clients with real requests​

import { declareAction } from '@tramvai/core';

const httpRequestAction = declareAction({
  name: 'http-request-action',
  async fn() {
    return this.deps.httpClient.get('/');
  },
  deps: {
    httpClient: HTTP_CLIENT,
  },
});

export const Page = () => {
  return <h1>Page</h1>;
};

Page.actions = [httpRequestAction];

How to provide environment variables?​

This addon provides a few important defaults:

  • Mock provider for ENV_MANAGER_TOKEN
  • Read env.development.js content from application root

So, any variables from env.development.js will be registered in envManager.

If you want to add custom variables for some stories, pass options for CommonTestModule (from @tramvai/test-mocks package) in story parameters:

const parameters: TramvaiStoriesParameters = {
  tramvai: {
    options: {
      env: {
        FOO: 'BAR',
      },
    },
  },
};

Troubleshooting​

"Rendered more hooks than during the previous render."​

In case of using both fastRefresh and strictMode in reactOptions in Storybook config in main.js, you might see the error message above.

This is a known issue in Storybook itself, as a temporary workaround you can simply disable the strictMode in Storybook config.

Won't work:

.storybook/main.js
module.exports = {
  reactOptions: {
    fastRefresh: true,
    strictMode: true,
  },
};

Works:

.storybook/main.js
module.exports = {
  reactOptions: {
    fastRefresh: true,
  },
};

Contribute​

For testing changes in this plugin locally, you need a few steps:

  1. [tramvai repo] Copy examples-standalone/storybook application to different folder, e.g. storybook-app
  2. [storybook-app] run git init in this folder (@storybook/builder-webpack5 uses as root the first parent directory containing .git folder)
  3. [storybook-app] Update there all tramvai dependencies in package.json
  4. [tramvai repo] Copy plugin build output from packages/tramvai/storybook-addon/lib
  5. [storybook-app] Paste into the storybook-app/node_modules/@tramvai/storybook-addon/lib folder
  6. [storybook-app] Run storybook in nested folder cd storybook && npm run storybook