CLI: MDX1 automigration

[shilman]

Is your feature request related to a problem? Please describe

Storybook 7 contains a variety of breaking changes, which may affect users who are upgrading.

If a user is using Storybook Docs MDX, upgrading their docs from MDX1 to MDX2 is one of the more problematic migrations. It is a manual process, and may involve editing a number of files to get to their Storybook to build properly.

Describe the solution you'd like

To address this issue, we added opt-in, legacy MDX1 support. This issue takes that work further by proposing modifications to the upgrade flow around this new support.

Current flow

1. User upgrades using sb upgrade
   1. If user has .stories.mdx, they are prompted to upgrade to MDX2
2. User runs their storybook
   1. If they don’t heavily use MDX, it might work out of the box. It might fail due to that, or other breaking changes.
   2. If they use a lot of MDX, they will likely hit errors & need to fix.
      1. User fixes those errors by hand and successfully upgrades to MDX2
      2. User gets frustrated, installs opt-in MDX1 support, and foregoes the upgrade process so that they can get a working Storybook. At some point later, they manually upgrade to MDX2, or not.

Proposed flow

1. User upgrades using sb upgrade
   1. If users have .stories.mdx , they prompted to upgrade to install legacy MDX1 support with an explanation why they might want to do this.
   2. If user has legacy MDX1 support installed, they are prompted to upgrade to MDX2 (and why they might want to skip until they have a working SB7, and how they can automatically upgrade in the future).
2. Users run their Storybook with MDX1
   1. MDX should work out of the box, and user can focus on fixing errors due to other breaking changes.
3. After the upgrade, each time they run Storybook, they are met with a warning that MDX1 support is deprecated and how they can upgrade to MDX2.
   1. At some point later, they manually upgrade to MDX2 or not.

Changes required

• Add new legacy-mdx1 automigration that:
  • Installs & configures the package if you're using .stories.mdx files
  • note that this should be run AFTER the mdx-1-to-2 migration

We've found ${chalk.yellow(storiesMdxFiles.length)} '.stories.mdx' files in your project.

Starting in Storybook 7, we've upgraded to MDX2 (https://mdxjs.com/blog/v2/) for documentation. MDX1, which was the default in earlier versions of Storybook, is no longer maintained.

If you use lots of MDX in your project, you are likely to encounter breaking syntax changes when upgrading to MDX2. To smooth the transition, we've created a "legacy MDX1 mode" which processes your MDX files the old way. There are lots of other breaking changes in SB7, so enabling this mode can be a quick way to get to a working state. Then, once you've verified that everything else is working, you can upgrade to MDX2 as a separate step.

For more info, see: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#legacy-mdx1-support

Would you like us to enable legacy MDX1 mode for you? [Yn]

• Update mdx-1-to-2 automigration to:
  • Only run if mdx1-csf is installed used
  • Remove mdx1-csf dep and configuration

We see that you are using the legacy MDX1 mode to handle MDX files.

Once you've verified that you have a working Storybook7 install, we recommend that you disable this mode and upgrade your files to MDX2 (https://mdxjs.com/blog/v2/), which contains breaking changes from V1. We can try to automatically upgrade your MDX files to MDX2 format using some common patterns.

Some steps might require manual intervention. You can find a full guide for how to manually upgrade your files here: ${chalk.cyan('https://storybook.js.org/docs/7.0/react/writing-docs/mdx#breaking-changes')}

• Add mdx1-csf runtime deprecation
  • Tells users to upgrade & how
• Update migration guide to include this "phased" approach

Messages

[JReinhold]

So the proposal is basically to not make users migrate all their MDX1 -> MDX2 while also doing the other migrations, but instead recommend them to stay on MDX1 and then nudge to migrate later when their SB is working.

I assume because we feel that the MDX migration can be quite big for them, so it's better to do separately - and because the errors that MDX2 throws aren't very clear.

I think that's a fine idea, no objections.

[shilman]

@yannbf @JReinhold @tmeasday One wrinkle is that MDX1 is currently Webpack only, so that makes it all a bit more complicated 😭

[shilman]

Discussed this with @ndelangen and @yannbf and we decided to improve our upgrade experience instead:

1. Try to detect MDX errors and point them to our migration guide
2. Suggest in the migration guide to install the MDX VScode addon and enable the experimentalLanguageServer option, which will automatically check your MDX files OR install https://github.com/mdx-js/eslint-mdx/