Experimental MDXv2 Support in Storybook 6.5

mdx-v2-sb-6.5.md

Experimental MDXv2 Support in Storybook 6.5

The MDX team has just released the long-awaited MDXv2 with dramatically better syntax and performance. It's a huge win for the community! 🎉

Now I'm excited to announce experimental support in Storybook 6.5. This gist summarizes how to try it out, how to report bugs, and known gotchas that you might encounter along the way.

Installation

Since MDXv2 is a breaking change, it's an opt-in feature in Storybook 6.5.

To try it out, first upgrade to 6.5 prerelease:

npx sb upgrade --prerelease

Then install the mdx2 package:

yarn add @storybook/mdx2-csf -D

Then add the previewMdx2 feature flag to your .storybook/main.js config:

module.exports = {
  features: {
    previewMdx2: true,
  },
};

Reporting issues

If you run into any problems, please file an issue on the Storybook monorepo, ideally with a reproduction: https://github.com/storybookjs/storybook

If you'd rather discuss interactively, message the #sb-docs channel on the Storybook Discord https://discord.gg/storybook

Gotchas

We're still learning the ins and outs of MDXv2. Here are some known gotchas.

Template literals

One pattern that we used in MDXv1 was:

<style>{`
  .class1 {
    ...
  }

  .class2 {
    ...
  }
`}</style>

This no longer works in MDXv2. If you're using this pattern in your code, add indentation as follows to make it MDXv2 compatible:

<style>
  {`
    .class1 {
      ...
    }

    .class2 {
      ...
    }
  `}
</style>

Ongoing discussion here: mdx-js/mdx#1945