codemod

Storybook Codemods

Storybook Codemods is a collection of codemod scripts written with JSCodeshift. It will help you migrate breaking changes & deprecations.

CLI Integration

The preferred way to run these codemods is via the CLI's migrate command.

To get a list of available codemods:

npx -p @storybook/cli@next sb migrate --list

To run a codemod <name-of-codemod>:

npx -p @storybook/cli@next sb migrate <name-of-codemod> --glob="**/*.stories.js"

Installation

If you want to run these codemods by hand:

yarn add jscodeshift @storybook/codemod --dev

• @storybook/codemod is our collection of codemod scripts.
• jscodeshift is a tool we use to apply our codemods.

After running the migration commands, you can remove them from your package.json, if you added them.

How to run a codemod script

From the directory where you installed both jscodeshift and @storybook/codemod run:

Example:

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/update-organisation-name.js . --ignore-pattern "node_modules|dist"

Explanation:

<jscodeShiftCommand> -t <transformFileLocation> <pathToSource> --ignore-pattern "<globPatternToIgnore>"

Transforms

update-organisation-name

Updates package names in imports to migrate to the new package names of storybook.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/update-organisation-name.js . --ignore-pattern "node_modules|dist"

There's a mapping of paths we replace but this example explains the gist of it:

Example:

import { storiesOf } from '@kadira/storybook';
import { linkTo } from '@kadira/storybook-addon-links';

Becomes

import { storiesOf } from '@storybook/react';
import { linkTo } from '@storybook/addon-links';

update-addon-info

Replaces the Info addon's deprecated addWithInfo API with the standard withInfo API.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/update-addon-info.js . --ignore-pattern "node_modules|dist"

Example:

storiesOf('Button').addWithInfo('simple usage', 'This is the basic usage of the button.', () => (
  <Button label="The Button" />
));

Becomes

storiesOf('Button').add(
  'simple usage',
  withInfo('This is the basic usage of the button.')(() => <Button label="The Button" />)
);

With options example:

storiesOf('Button').addWithInfo(
  'simple usage (disable source)',
  'This is the basic usage of the button.',
  () => <Button label="The Button" />,
  { source: false, inline: true }
);

Becomes

storiesOf('Button').add(
  'simple usage (disable source)',
  withInfo({
    text: 'This is the basic usage of the button.',
    source: false,
    inline: true,
  })(() => <Button label="The Button" />)
);

add-component-parameters

This tries to smartly adds "component" parameters to all your existing stories for use in SB Docs.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/add-component-parameters.js . --ignore-pattern "node_modules|dist"

For example:

import { Button } from './Button';
storiesOf('Button', module).add('story', () => <Button label="The Button" />);

Becomes:

import { Button } from './Button';
storiesOf('Button', module)
  .addParameters({ component: Button })
  .add('story', () => <Button label="The Button" />);

Heuristics:

• The storiesOf "kind" name must be Button
• Button must be imported in the file

storiesof-to-csf

This converts all of your "old-style" storiesOf stories into Component Story Format (CSF), which uses standard ES6 modules.

NOTE: The output of this transformation may require manual editing after running the transformation. storiesOf API allows multiple "kinds" (components) to be declared per file, but CSF only allows a single component per file. Therefore, if you use this feature in your input stories, you will need to split up the resulting outputs by hand. You'll see a warning at the console if you need to hand edit.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/storiesof-to-csf.js . --ignore-pattern "node_modules|dist"

For example:

storiesOf('Button', module)
  .add('story', () => <Button label="Story 1" />)
  .add('second story', () => <Button label="Story 2" onClick={action('click')} />)
  .add('complex story', () => (
    <div>
      <Button label="The Button" onClick={action('onClick')} />
      <br />
    </div>
  ));

Becomes:

export default {
  title: 'Button',
};

export const story = () => <Button label="Story 1" />;

export const story2 = () => <Button label="Story 2" onClick={action('click')} />;
story2.story = { name: 'second story' };

export const story3 = () => (
  <div>
    <Button label="The Button" onClick={action('onClick')} />
    <br />
  </div>
);
story3.story = { name: 'complex story' };

Heuristics:

• If a file has any default export, it will be skipped
• If a file has multiple storiesOf declarations, it will convert each one separately. This generates invalid ES6, but you can edit the file by hand to split it into multiple files (or whatever is appropriate).

csf-to-mdx

This converts all of your CSF Component Stories into MDX syntax, which integrates story examples and long-form documentation.

NOTE: The output of this transformation may require manual editing after running the transformation. MDX is finnicky about the top-level statements it allows. For example, variables should be defined with exports, meaning const foo = 5; should be rewritten as export const foo = 5;. We don't do this transformation automatically, since you may prefer to refactor your stories.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/csf-to-mdx.js . --ignore-pattern "node_modules|dist"

For example:

export default {
  title: 'Button',
};

export const story = () => <Button label="Story 1" />;

export const story2 = () => <Button label="Story 2" onClick={action('click')} />;
story2.story = { name: 'second story' };

Becomes:

import { Meta, Story } from '@storybook/addon-docs/blocks';

# Button

<Meta title='Button'>

<Story name='story'><Button label="Story 1" /></Story>

<Story name='second story'>
  <Button label="Story 2" onClick={action('click')} />
</Story>

mdx-to-csf

This converts all your MDX stories into Component Story Format.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/mdx-to-csf.js . --ignore-pattern "node_modules|dist" --extensions=mdx

For example:

import React from 'react';
import Button from './Button';
import { Meta, Story } from '@storybook/addon-docs/blocks';

<Meta title='Button' />

<Story name='basic stories'><Button label='The Button' /></Story>

Becomes:

import React from 'react';
import Button from './Button';

export default {
  title: 'Button',
};

export const basicStory = () => <Button label="The Button" />;
basicStory.story = {
  name: 'basic stories',
};

upgrade-hierarchy-separators

Starting in 5.3, Storybook is moving to using a single path separator, /, to specify the story hierarchy. It previously defaulted to | for story "roots" (optional) and either / or . for denoting paths. This codemod updates the old default to the new default.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/upgrade-hierarchy-separators.js . --ignore-pattern "node_modules|dist"

For example:

storiesOf('Foo|Bar/baz');
storiesOf('Foo.Bar.baz');

export default {
  title: 'Foo|Bar/baz.whatever',
};

Becomes:

storiesOf('Foo/Bar/baz');
storiesOf('Foo/Bar/baz');

export default {
  title: 'Foo/Bar/baz/whatever',
};

csf-hoist-story-annotations

Starting in 6.0, Storybook has deprecated the .story annotation in CSF and is using hoisted annotations.

./node_modules/.bin/jscodeshift -t ./node_modules/@storybook/codemod/dist/transforms/csf-hoist-story-annotations.js . --ignore-pattern "node_modules|dist" --extensions=js

For example:

export const Basic = () => <Button />
Basic.story = {
  name: 'foo',
  parameters: { ... },
  decorators: [ ... ],
};

Becomes:

export const Basic = () => <Button />
Basic.storyName = 'foo';
Basic.parameters = { ... };
Basic.decorators = [ ... ];

The new syntax is slightly more compact, is more ergonomic, and resembles React's displayName/propTypes/defaultProps annotations.