babel-plugin-storybook-csf-title

A Babel plugin to generate titles for Storybook CSF stories at compile time, typically based on the story file's file name.

Usage

The plugin adds a title property to all transformed files, based on the result of a toTitle function that is to be provided as an option to the plugin.

Assuming toTitle: () => 'foo', there are three general scenarios:

1️⃣ The file does not provide a default export

In this scenario, the plugin creates a default export { title: "foo" }.

E.g.,

1import React from 'react';
2import Component from './index';
3
4export const Example = () => <Component />;

is transformed into

1import React from 'react';
2import Component from './index';
3
4export const Example = () => <Component />;
5
6export default { title: 'foo' };

2️⃣ The file provides an object as its default export

In this scenario, the plugin adds a title: foo property to the existing export.

E.g.,

1import React from 'react';
2import Component from './index';
3
4export default { 
5    something: 'something'
6};
7
8export const Example = () => <Component />;

is transformed into

1import React from 'react';
2import Component from './index';
3
4export default { 
5    title: 'foo'
6    something: 'something'
7};
8
9export const Example = () => <Component />;

If the existing export already contains a title property, an error is thrown.

3️⃣ The file provides a non-object as its default export

If the renameDefaultExportsTo option is set, the plugin assumes that the default export is a component, and moves this component to a named export of the name ${renameDefaultExportsTo}. It then creates a default export { title: "foo" }.

E.g., assuming renameDefaultExportsTo is "Default",

1import React from 'react';
2import Component from './index';
3
4export default () => <Component />;

is transformed into

1import React from 'react';
2import Component from './index';
3
4export const Default = () => <Component />;
5
6export default { 
7    title: 'foo'
8};

If a ${renameDefaultExportsTo} export already exists, an error is thrown.

Installation

Install the plugin e.g. via yarn;

yarn add --dev babel-plugin-storybook-csf-title

In your Babel configuration, add babel-plugin-storybook-csf-title as a plugin:

1plugins: [
2    ['babel-plugin-storybook-csf-title', { toTitle: require('./your-to-title-function') }],
3]

Note that the plugin really only makes sense for story files. You will want to make sure it is only applied to exactly these files, e.g. like this:

1/* add plugin to babel, however disable it by default */
2plugins: [
3    ['babel-plugin-storybook-csf-title', false], 
4],
5/* enable the plugin for all files that match your story name pattern */
6overrides: [{ 
7    include: /\/stories\.(ts|tsx)$/, 
8    plugins: [
9        ['babel-plugin-storybook-csf-title', { toTitle: require('./your-to-title-function') }]
10    ]
11}]

Options

The plugin takes three options, toTitle (required), ifTitleFound (optional), and renameDefaultExportsTo (optional):

• toTitle is a function that, for every story file that is transformed, recieves Babel's state object, and must return the story file's title as a string. Most toTitle implementations will make decisions based on state.filename.

• ifTitleFound is an optional string value that may either be set to:

  • 'skip' - skips adding a title if it has already been manually specified in the code
  • undefined (or any other value) - raise an error if processing a file that already defines a title

• renameDefaultExportsTo is an optional string value that controls scenario 3 as described above. It is undefined by default.

Generating meaningful story names

In most cases, the story name will be generated based on the story file's file name. Here's a possible implementation of toTitle for a yarn workspaces-style monorepo setup:

1const path = require('path');
2const pkgUp = require('pkg-up');
3
4module.exports = (state) => {
5
6    // find the closest package.json
7    const packageJsonPath = pkgUp.sync({ cwd: state.filename });
8
9    // read the package.json
10    const packageJson = require(packageJsonPath);
11
12    // get the path of the story file relative to the package root
13    const { dir: packageJsonDir } = path.parse(packageJsonPath);
14    const { dir: fileDir, name: fileName } = path.parse(path.relative(packageJsonDir, state.filename));
15
16    const storybookPath = [
17        // package name; "/" has meaning to storybook, hence replace a possible "/" by "|"
18        packageJson.name.replace('/', '|'),
19
20        // file dir
21        ...fileDir.split(path.sep),
22    ];
23
24    // handle file names
25    if (fileName === 'examples' || fileName === 'stories') {
26        // nothing to do
27    } else if (fileName.endsWith('.stories')) {
28        storybookPath.push(fileName.slice(0, '.stories'.length + 1));
29    } else if (fileName.endsWith('.examples')) {
30        storybookPath.push(fileName.slice(0, '.examples'.length + 1));
31    }
32
33    return storybookPath.join('/');
34}

Contributions

Contributions to babel-plugin-storybook-csf-title are welcome! Please see CONTRIBUTING.md for details.

License

Copyright (c) 2020 Atlassian and others. Apache 2.0 licensed, see LICENSE file.