1805573 - Get MDX files working in Storybook

Status: RESOLVED FIXED

(Toolkit :: UI Widgets, enhancement)

Description

[Hanna Jones [:hjones]]

.mdx is a file format supported by Storybook to enable users to write markdown documentation alongside component demos. According to the docs, writing .mdx stories should work out of the box without any additional configuration, but we seem to be running into a known dependency version issue which results in Error: Can't resolve '@mdx-js/react' whenever I try to add an .mdx story and run storybook locally.

There are some suggestions in that Github issue thread about possible workarounds/fixes, but it might take some trial and error to get it working in our case.

Long term I don't know if we'll actually want to use .mdx for all of our component stories, but it will be handy for docs only pages we want to add.

Comment 1

[Hanna Jones [:hjones]]

Attachment: WIP: Bug 1805573 - enable mdx2 to fix dependency version issues

Comment 2

[Hanna Jones [:hjones]]

Attachment: WIP: Bug 1805573 - fix storybook support for mdx files

This works but is probably not ideal as I had to wipe away my package-lock.json, so there's a ton of changes to that file.

Basically the steps I took were:

• remove node_modules and package-lock.json from the storybook dir
• run npm i @mdx-js/react@^1.6.22 -D --legacy-peer-deps as suggested in the Github thread
• run ./mach npm i --prefix=browser/components/storybook

This seems to work on both my Mac and Windows machines and has the added benefit of getting rid of a lot of version mismatch warnings we were seeing when running ./mach storybook install. That being said, there may have been a simpler way to resolve the version mismatch issues.

Comment 3

[BugBot [:suhaib / :marco/ :calixte]]

The severity field is not set for this bug.
:mossop, could you have a look please?

For more information, please visit auto_nag documentation.

Comment 4

[BugBot [:suhaib / :marco/ :calixte]]

The Bugbug bot thinks this bug should belong to the 'Toolkit::XUL Widgets' component, and is moving the bug to that component. Please correct in case you think the bot is wrong.

Comment 5

[BugBot [:suhaib / :marco/ :calixte]]

The product::component has been changed since the backlog priority was decided, so we're resetting it.
For more information, please visit auto_nag documentation.

Comment 6

[Hanna Jones [:hjones]]

Attachment: Bug 1805573 - make it possible to write .stories.md or .stories.mdx documentation r=mstriemer,tgiles

This patch both fixes the dependency issues that we were running into when writing .stories.mdx stories and gives us the ability to write .stories.md docs only vanilla markdown stories.

To get the MDX stories working I had to clear out my package-lock.json and install @mdx-js/react with the --legacy-peer-deps flag as described here: https://github.com/storybookjs/storybook/issues/18094#issuecomment-1112883092

Let me know if you run into issues with installing dependencies and running Storybook given all the changes. There was a different solution I explored in January to enable MDX2 support, but I couldn't seem to resolve all the dependency version mismatch issues there anymore. There will probably be follow up work to update all of this after Storybook v7 is officially released in March.

To enable us to write .stories.md docs only stories I added a custom Webpack loader that takes markdown and transforms it into docs only MDX, then runs that through all the other necessary loaders. There's definitely some follow up work here too - for example right now all our docs only pages get put in a "Docs" folder because I ran out of steam for exploring a way for us to specify/parse out a path and name for the docs stories.

Comment 7

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/ac9be11deed0
make it possible to write .stories.md or .stories.mdx documentation r=mstriemer,tgiles

Comment 8

[Iulian Moraru]

https://hg.mozilla.org/mozilla-central/rev/ac9be11deed0