[Tracking]: Monorepo-ready Automigrations

[valentinpalkovic]

Problem statement

In the recent State of JS surveys, users complained about using Storybook. That's why we invested so much into automigrations for major releases.

Unfortunately, we've observed lots of problems in upgrading real-world monorepos. Automigrations fail explicitly, because they detect multiple projects and the automigrations know that they're not equipped to handle this properly. This is better than if they upgrade the wrong packages and/or stories, leaving the project in a broken or inconsistent state, but it still sucks.

This is a pretty big problem: 30% of Storybook projects are in monorepos, 35% of “viable” projects with 20+ stories, and 40% of “ideal” projects with 200+ stories. So our “best” users are getting the worst upgrade experience!

More broadly, Storybook’s monorepo support sucks in general: a community RFC begging for a well-supported monorepo setup is by far the most upvoted RFC despite no solution in sight yet. Fixing automigrations for monorepos does not solve the general problem, but it is a step in the right direction. And giving space for this work might help unlock a more general solution.

Milestones

Milestone: Finalize possible upgrade flows in monorepos

Owner: @yannbf
Complete By: 21. May 2025

• Collect the top-5 most common monorepo setups
• Write down the optimal upgrade flow/experience for all of them

Milestone: Enhancing Storybook utils to be mono-repo aware

Owner: @valentinpalkovic, @yannbf
Complete By: 23. May 2025

• Adjust storybook add/remove (fault-tolerant)
• Adjust storybook upgrade --config-dir flag to support multiple config dirs
• Adjust JsPackageManager class and related utils like getStorybookData
• Config dir detection utilities (support custom config dirs?!)
• Performance: Introduce --skip-install to storybook add/remove to skip installations

Milestone: Adjust upgrade and automigrations

Owner: @valentinpalkovic, @yannbf
Complete By: 29. May 2025

• Adjust upgrade to detect multiple projects and prompt the user what we are about to change
• Update Storybook dependencies in all relevant package.jsons
• Consider custom config dirs via --config-dir option
• Adjust automigrations to apply changes for all detected Storybooks
• If not in mono-repos, the behaviour stays as is
• Revamp doctor command and helpers to expand package checks to all related package.jsons (dev, doctor, upgrade)

Milestone: QA Top-5 monorepo setups

Owner: @yannbf
Complete By: 30. May 2025

• Test all top-5 monorepo scenarios
• Make sure that the Storybook init experience should not be affected by any of the made changes

Milestone: Telemetry updates

Owner: @shilman
Complete By: 28. May 2025

• Make sure the upgrade process accounts for telemetry changes to track the success of the project

Milestone: Documentation updates

Owner: @valentinpalkovic
Complete By: 29. May 2025

• Update upgrade documentation and guide mono-repo users

Milestone: Create/modify node-logger class

Owner: @valentinpalkovic
Complete By: 29. May 2025

• Encapsulate upgrade logging into a class
• Don’t change current logging related libraries

========= Everything below this line is strictly nice-to-have =========

Milestone: Exchange current logging utils by modern ones

Owner: @valentinpalkovic
Complete By: 30. May 2025

• Replace prompt library and other logging related utils by a modern alternative

Milestone: RFC for recommended mono-repo support

Owner: @yannbf
Complete By: 2. June 2025