CSF stories with MDX docs recipe fails

[Michael Shilman]

Importing a CSF story into an MDX doc per the recipe fails.

// Button.stories.js
import { Button } from './Button';
export const Basic = () => <Button label="hi" />;

{/* Button.stories.mdx */}
import { Meta, Story } from '@storybook/addon-docs';
import * as stories from './Button.stories.jsx';

<Meta title="Button" />

<Story story={stories.Basic} />

In MDX1 this generates the following code:

In MDX2 this generates the equivalent of:

<Story story={stories.Basic} />

Since there is no-generated name, Storybook's lookup fails.

[Michael Shilman]

NOTE: As a workaround you can define the name manually for now:

<Story name="Basic" story={stories.Basic} />

[n028]

I tried to dig into this issue because I am too lazy to manually add the name to every imported Story :) I think it is happening because the plugin is returning an unmutated root. One could expect these lines to actually add the name attribute to imported stories, just like it used to do with mdx1-csf, but here ast is not a reference to the root, changing it will not have any effect on the tree returned by the plugin. Aren't these lines dead code?

I can't come up with an ideal solution because imported stories are matched while traversing the Babel AST. Traversing the root tree to match these imported stories again sounds pretty silly, but is there another way to "sync" both ASTs?

I've tried to come up with something anyway, but I'm afraid it is quite stupid :/

[Tom Coleman]

Has anyone tried switching it to <Story of={stories.Basic} /> in a 7.0 beta? I think that would work. We could probably make <Story story={...} /> work the same way.

[Michael Shilman]

@tmeasday That would probably work but it would be a breaking change. The old recipe is that the CSF file declares the story functions but the MDX file is the one that actually defines them. If we changed the semantics of story={...} to match of={...}, then the user would need to:

1. update their CSF file to have a default export
2. probably update their MDX Meta to reference that default export (or not, I'm not sure?)

At that point they might as well upgrade to the of={...} format. We could force them to make that upgrade. This is a breaking release after all.

However, I think the spirit of this issue is that we support the old recipe for now, with deprecation warnings, and provide a migration path. WDYT?

[n028]

At that point they might as well upgrade to the of={...} format. We could force them to make that upgrade. This is a breaking release after all.

Just in case my opinion deserves any credit, the different small issues I ran into while sticking to the old *.stories.mdx eventually got me to just move forward and undertake that upgrade. While being refreshing (mostly because it looks more concise and it removes that "I know I'm using Storybook in an outdated fashion" burden), it still required a bit of time and effort.

Sure this is a major release and breaking changes are to be expected, but I'm pretty convinced a lot of users actually need some of the changes introduced with 7.0 so that it integrates fine (i.e. no workaround needed) in their development workflow (e.g. better pnpm & vite support). Most breaking changes are fine and pretty easy to overcome, but that one is quite effort-consuming, especially for docs-heavy Storybooks, and some users might just not have time and resource to undertake that change. At least yet!

IMHO, support & depreciation warnings are the way to go!
I'd even go for "aggressive" depreciation warnings to encourage them further

[Tom Coleman]

Thanks @Dschungelabenteuer, yes, we are aiming to make this change opt-in (and also provide more tools to make it easier to do so), so we'll aim to fix up accidentally breakages like this.

@shilman OK, I misunderstood. Is your code snippet at the top missing a <Meta> for the Button.stories.mdx file then?

[Michael Shilman]

@tmeasday correct. i've updated the snippet (untested)