[RFC] Split Storybook CLI

[JReinhold]

Status: in-review; championed by @JReinhold

Summary

The current Storybook CLI contains all possible actions to run, even those that are rarely used day-to-day, and are used with npx instead to always use the latest version, eg. npx storybook@latest upgrade. This incurs unnecessary bloat in user's projects.

I propose to split the CLI into multiple packages depending on their use case, so users only have to install the minimal necessary packages to their project, speeding up both init and usage of Storybook.

Problem Statement

The Storybook CLI is one package that contains all the functionality a user would want from a CLI. That includes common day-to-day flows like dev for starting the development server and build for creating a static build. However it also includes flows that are less common, like upgrade, migrate, and sandbox. This bloats the CLI package for all users, even though 99 % of all usage is either for dev or build.

Some of the more advanced workflows like migrate includes a lot of big dependencies that further contributes to this problem of CLI bloat.

In the end, the bloat results in:

• slower install time
• bigger foot print on the user’s disk
• more modules in the user’s project and lock file.

Non-goals

This proposal only concerns itself with the CLI, and not any other part of the Storybook core.

Implementation

In short I propose to split the CLI into multiple separate packages:

1. storybook / sb
2. @storybook/cli
3. create-storybook
4. @storybook/toolbox - or another similar name

1. storybook CLI (and aliases)

storybook will become a thin wrapper around the other packages listed below, and will still be installed in the users’ projects. This wrapper will ensure that the CLI remains backwards compatible, and there are no current plans to get rid of this immediately.

Any command run with this will “redirect” to one of the others, by calling eg. npx create-storybook or npx @storybook/toolbox <COMMAND> - using the package manager specified by the user.

• npx storybook dev → npx @storybook/cli dev
• npx storybook build → npx @storybook/cli build
• npx storybook init → npx create-storybook
• npx storybook upgrade → npx @storybook/toolbox upgrade.
• npx storybook automigrate → npx @storybook/toolbox automigrate
• …

2. @storybook/cli

@storybook/cli will be the new CLI that is supposed to be installed in users’ projects, alongside storybook. It will contain the dev and build workflows, which are seen as essential for day-to-day usage of Storybook.

The user could use @storybook/cli directly, but we will keep storybook in docs and in initialized projects to cause minimal change, as it should be minimal overhead to call storybook instead of @storybook/cli (which we need to confirm before starting this).

3. create-storybook

Will be the CLI to initialize Storybook in a project. Having this as a separate CLI will make the initialization as fast as possible. Using create-storybook will mean that the create alias built into package managers will work, ie. npm create storybook is equivalent to npx create-storybook

4. @storybook/toolbox

Will be a new CLI package that will be used to run any of the other workflows, that are not used day-to-day, and don’t necessarily have to be super fast:

1. add
2. babelrc
3. upgrade
4. info
5. migrate
6. extract - will be deprecated, and fully removed in 8.0
7. sandbox|repro
8. link
9. automigrate

Prior Art

Svelte(Kit) has split some functionality into separate packages, create-svelte, @sveltejs/kit , @sveltejs/package , svelte-check and maybe more.

Deliverables

1. Move @storybook/cli to @storybook/toolbox
2. Deprecate the extract command
3. Re-implement dev and build back in @storybook/cli
4. Re-implement init in create-storybook
5. Make storybook a wrapper that doesn’t depend on @storybook/cli but instead calls it via the CLI
6. Automigration to install @storybook/cli in user’s projects
7. Investigate if there are still performance wins by async loading code paths to dev, build, and the tools in @storybook/toolbox.
8. Log to telemetry which CLI package (and with which version specifier) was runned, ie. npx storybook init vs npx create-storybook vs npm create storybook , or npx storybook dev vs npx @storybook/cli dev, etc.

Risks

No response

Unresolved Questions

• How big is the performance overhead of calling the storybook wrapper vs calling the commands directly?
• … And can it be done reliably across different environments?

Alternatives considered / Abandoned Ideas

1. Single CLI that downloads code paths on-demand

Norbert have talked about a different approach to solve the same problem. Instead of splitting the CLI into different packages, we would keep the same single-package CLI but instead download the code paths on demand.

So if the user runs sb upgrade, the CLI would first download a tarball that contains all the code for ugprade, and then run it.

The upside of that approach is that we keep the existing API as is, no changes necessary.

The downside of this approach is that we would basically be implementing our own mini package-manager inside the CLI, which comes with it’s own level of complexity. We would need to figure out where to store and download the (versioned) code paths from, extract them, and run them. I believe Norbert have already successfully implemented parts of this in a package manager agnostic way. The code would need to be prebundled, which might be fine, but breaks if we ever introduce architecture specific dependencies (like esbuild has different versions per architecture, and the package managers handles this automatically).

Personally I’m against of this approach, as I would rather travel the less magical and more predictable path, at the cost of user convenience.

2. Async loading of code paths

Recent introduction of Prettier to the CLI [forced us to asynchronously import Prettier](#21269), because it caused the eval step to slow down significantly because of Prettier’s large size. We’ve discussed taking this a step further by asynchronously require all code paths, to only evaluate what is needed to run the given command. While this might speed up the execution of the command, it won’t affect the package size of the CLI at all, which is why I don’t think this approach is enough.

Rollout Plan

With the current plan of still using storybook as a lean wrapper, there should be no breaking changes here. However this is a minor release, given that we want to install @storybook/cli in user’s projects next to storybook.

Even if it turns out the storybook wrapper adds significant overhead - in a way that would make us not recommend that at all - we could still have it as part of the project to be backwards compatible, possibly deprecating it in a later major release.

References

#22416

[TrySound]

Hi @JReinhold. Were there any discussions about this?

[kasperpeulen]

We are working on it. Probably will land in 8.3!
#28471

[kasperpeulen]

It is ready for review here!
#28519