@storybook/codemod

What is @storybook/codemod?

The @storybook/codemod package is a collection of codemod scripts that help developers automate the process of making code changes and migrations in projects using Storybook. These scripts are particularly useful for upgrading between major versions of Storybook by automatically adjusting the code to fit new APIs and practices.

What are @storybook/codemod's main functionalities?

Transform Storybook configuration

This feature allows you to automatically transform and update your Storybook configuration files to adhere to new organizational standards or API changes in newer versions of Storybook.

npx @storybook/codemod@latest update-organisation --glob=".storybook/*.js"

Migrate stories to Component Story Format (CSF)

Converts stories written in the older 'storiesOf' format to the newer Component Story Format (CSF), which is more modular and easier to maintain.

npx @storybook/codemod@latest storiesof-to-csf --glob="src/**/*.stories.js"

Rename deprecated addParameters to use args

This script updates the deprecated 'addParameters' method calls in your stories to the new 'args' format, helping you to keep your codebase up to date with the latest Storybook practices.

npx @storybook/codemod@latest add-parameters-to-args --glob="src/**/*.stories.js"

Other packages similar to @storybook/codemod

jscodeshift

jscodeshift is a toolkit for running codemods over multiple JavaScript or TypeScript files. It provides a more general-purpose approach compared to @storybook/codemod, which is specifically tailored for Storybook-related transformations.

react-codemod

react-codemod offers a collection of React-specific transformations to help update React APIs and patterns. While it targets React specifically, unlike @storybook/codemod, it does not focus on Storybook configurations or story formats.

README

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 sb migrate --list

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

npx 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).

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.