[Bug]: Unable to use Description without a Story in MDX

[will-stone]

Describe the bug

An MDX (docs only) story with a Description errors with:

No primary story defined for docs entry. Did you forget to use `<Meta>`

To Reproduce

Create an MDX story file with Meta and a Description of a component:

import { Description, Meta } from "@storybook/addon-docs";
import { Button } from "./Button";

<Meta title="Button" />

<Description of={Button} />

Reproduction: https://github.com/will-stone/storybook-description-bug

System

Environment Info:

  System:
    OS: macOS 12.6.1
    CPU: (10) arm64 Apple M1 Max
  Binaries:
    Node: 16.18.1 - ~/.local/share/nvm/v16.18.1/bin/node
    npm: 8.19.2 - ~/.local/share/nvm/v16.18.1/bin/npm
  Browsers:
    Chrome: 107.0.5304.110
    Firefox: 107.0
    Safari: 16.1
  npmPackages:
    @storybook/addon-essentials: ^7.0.0-alpha.53 => 7.0.0-alpha.53
    @storybook/addon-interactions: ^7.0.0-alpha.53 => 7.0.0-alpha.53
    @storybook/addon-links: ^7.0.0-alpha.53 => 7.0.0-alpha.53
    @storybook/react: ^7.0.0-alpha.53 => 7.0.0-alpha.53
    @storybook/react-vite: ^7.0.0-alpha.53 => 7.0.0-alpha.53
    @storybook/testing-library: ^0.0.13 => 0.0.13

Additional context

This used to work (I last tested on alpha 48 but not sure which alpha between then and now was the one that changed). It is useful to be able to grab the JSDoc description of components/functions without having a Story. For example, we use this as a way to document our hooks and utility functions.

[nerdyman]

I've got this issue too, after a bit of digging I found that @storybook/react-vite@7.0.0-alpha.52 is the cause. Version 7.0.0-alpha.51 renders without error. Also tried using the latest alpha release but it seems to cause more issues as it fails to render even with @storybook/react-vite pinned to 7.0.0-alpha.51.

[renato-bohler]

Same here, but I'm using Source instead of Description.

Here's another quick reproduction repo: https://github.com/renato-bohler/storybook-repro

The "Example" story will load if I remove the Source tag from the Example.stories.mdx file OR if I downgrade Storybook from 7.0.0-alpha.52 to 7.0.0-alpha.51.

Otherwise, the story will go blank and the following message appears on DevTools (<ju> would sometimes read <Source2>):

[HendrikPetertje]

Don't know if my issue is related, but I'll add it here too.

---

After upgrading to Storybook 7 I am noticing that my docs-only pages are no longer working if they have Story objects in them.

In our application we have 3 basic pages to describe the use of typography, icons and color.
all of these pages work fine if I remove any Story-blocks, if story-blocks are defined then the page raises the following error:

No primary story defined for docs entry. Did you forget to use `<Meta>`?

I have tried using the Story and Canvas components from 2 different places, both without success:

import { Meta, Story, Typeset, Canvas } from '@storybook/addon-docs';
import '~components/App/app.scss';

<Meta title="StyleGuide/Typography" />

...text content here...

## Header 1
<Canvas>
  <Story id="atoms-headers--header-one" />
</Canvas>

import { Meta, Title, IconGallery, IconItem } from '@storybook/addon-docs';
import { Story, Canvas } from '@storybook/blocks'
import '~components/App/app.scss';

<Meta title="StyleGuide/Iconography" />

...text content here...

### Loading (default)
<Canvas>
  <Story id="atoms-loading--default-loading" />
</Canvas>

Rendering the components without a story (so <Loading /> seems to work fine for now so I'll fallback to that)

System specifications:

 System:
    OS: macOS 13.0
    CPU: (16) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
  Binaries:
    Node: 18.11.0 - /usr/local/bin/node
    Yarn: 3.2.2 - /REDACTED/node_modules/.bin/yarn
    npm: 8.19.2 - /usr/local/bin/npm
  Browsers:
    Chrome: 108.0.5359.71
    Firefox: 107.0
    Safari: 16.1
  npmPackages:
    @storybook/addon-actions: ^7.0.0-alpha.54 => 7.0.0-alpha.54
    @storybook/addon-essentials: ^7.0.0-alpha.54 => 7.0.0-alpha.54
    @storybook/addon-interactions: ^7.0.0-alpha.54 => 7.0.0-alpha.54
    @storybook/addon-links: ^7.0.0-alpha.54 => 7.0.0-alpha.54
    @storybook/node-logger: ^7.0.0-alpha.54 => 7.0.0-alpha.54
    @storybook/preset-create-react-app: ^4.1.2 => 4.1.2
    @storybook/react: ^7.0.0-alpha.54 => 7.0.0-alpha.54
    @storybook/react-webpack5: ^7.0.0-alpha.54 => 7.0.0-alpha.54

[cmdcolin]

i ran into this same error also using same thing as @HendrikPetertje e.g. the Story with id inside a Canvas. I could also revert to just rendering a component directly but I like to use it in a Canvas cause then it has the "Show code" link on the canvas

[HendrikPetertje]

@cmdcolin, shall I make a seperate issue for it?

[renato-bohler]

Still a problem with 7.0.0-beta.6

[mdaoust-sidlee]

In 7.0.0-beta.8, I also have a similar error but this time related to the <Canvas> component.
Based on the doc here, I should be able to use the folowing without issue.

import { Meta, Canvas } from '@storybook/addon-docs';

<Meta title="Documentation/Foundations/Color" />

<Canvas>
  <h2>Some here</h2>
</Canvas>

[tmeasday]

Thanks for the detailed reports here folks!

Ok, in all three cases here (Description here, Source here and Canvas here) the issue is a call to storyById() in the block when we don't actually need the "primary" story.

Context:

• "docs only" stories used to create a story (thus the name), now they just create a docs entry (no story).
• Previously, we drove a lot of behaviour via the primary story (storyById() with no arguments), often via the parameters of that story.
• In the case of docs only stories that was really just a way of getting access to the project-level parameters.
• In docs2, we don't create a story for docs-only stories, (or .mdx files) so we should not be relying on storyById() unless we need it (e.g. <Source of="." />).

@JReinhold I think the right way forward on this issue is to create stories in our doc blocks SB for these usages where the docs context has no primary story. Then we'll have an easy reproduction to work from.

[HendrikPetertje]

thanks so much for digging in to this and finding the root cause! I don't have the bandwidth (time-wise) to go in and fix this right now today, but you have given a good start point and idea for a fix here! I'll keep an eye on this issue and if it isn't resolved due to all the stuff you folks already do (so amazingly) then I might give this a look in the near future!

[tmeasday]

Thanks for the kind words @HendrikPetertje! This is definitely on our radar for 7.0; @JReinhold and I will likely take a look in the new year together.

[tmeasday]

@JReinhold I proved the concept on #20362

[fmal]

I browsed the docs for 7.0 and got an impression that it's totally possible to use doc blocks in documentation-only mdx pages, but then run into this issue 😢 Would be a really useful feature, looking forward to it!

[shilman]

Whoopee!! I just released https://github.com/storybookjs/storybook/releases/tag/v7.0.0-beta.25 containing PR #20563 that references this issue. Upgrade today to the @next NPM tag to try it out!

npx sb@next upgrade --prerelease

Closing this issue. Please re-open if you think there's still more to do.

[jordanandree]

Thanks for the update! I upgraded my project to beta.25 and it seems to have fixed Description. However I'm still seeing the original error for ArgsTable, Source, and Canvas. Are there plans to fix these components as well?

[tmeasday]

There are @jordanandree! This ticket probably got closed early due to linking of the description PR to it.

[mdaoust-sidlee]

@JReinhold thanks for the quick reply and the explanations.

Did this work in 6.5, a canvas without stories? Then we might have introduced a bug.

Yeah, it was a feature documented here : Non-story content (last block on the page if the anchor does not work properly)

[JReinhold]

Thanks @mdaoust-sidlee, I've fixed it in #20803, should be released in the next couple of days.

[Alxandr]

@JReinhold does that mean you can no longer do multiple stories in one canvas?

[fmal]

@JReinhold using doc blocks in docs-only mdx files works great, the only caveat that i have run into is that you cannot import stories in .mdx docs-only files using the webpack aliases you defined in main.ts.

Something like this in a .mdx file:

import * as ComponentStories from '../../components/src/Component/Component.stories';

<Canvas of={ComponentStories.Default} />

will render correctly, while this:

import * as ComponentStories from '@components/Component/Component.stories';

<Canvas of={ComponentStories.Default} />

will fail with Invalid value passed to the 'of' prop. The value was resolved to a 'component or unknown' type but the only types for this block are: story

A little debug reveals that with the second scenario csfFiles passed to DocsContext is empty and then resolveOf throws.

The aliases itself are resolved because i can console.log in the mdx files the imported stories definitions, the problem is that exportsToCSFFile map is simply empty in DocsContext when using these aliases.

Did i run into some known limitation or is it a problem with my setup and you would need a reproduction from me?

[JReinhold]

@JReinhold does that mean you can no longer do multiple stories in one canvas?

Yes @Alxandr. Its implementation was weird and it had many unexpected behaviours. I'd love to hear which use cases you have for having multiple stories in a single canvas though, maybe we can revisit and find a suitable API for it in a later iteration. We just haven't really seen any good use cases that justifies it yet - but they might be out there.

@fmal that sounds like a bug for sure, could you open a new issue with a minimal reproduction?

[tmeasday]

Did i run into some known limitation or is it a problem with my setup and you would need a reproduction from me?

The issue here will be that we need to interpret that import in the story indexer (which reads your MDX file statically). I'm not sure it is feasible for it to understand things like aliases. WDYT @shilman?

[fauxparse]

I'd love to hear which use cases you have for having multiple stories in a single canvas

Showing all the variants of a small component (e.g. a button) in a summary view at the top of a document.

[Alxandr]

@JReinhold it's mostly a visual thing. What we have currently is this:

## Sizes

<Canvas>
	<Story name="Large">
		<Button>Large button</Button>
	</Story>
	<Story name="Small">
		<Button size="small">Small button</Button>
	</Story>
</Canvas>

which renders as following:

While also producing 2 stories. I use the same pattern multiple places:

I mostly just care about the border/look of the Canvas, not the source and features like that - so I'd be completely OK with not using Canvas but something else. It would be even better if that "something" had unstyled set on it.

The last example I have is this:

<Canvas withSource="none">
	<Unstyled>
		<H1>H1 - Heading - Overskrift</H1>
		<H2>H2 - Form title - Skjematittel</H2>
		<H3>H3 - Section title - Grupperingstittel</H3>
		<H4>H4 - Form elements title - Tittel over skjemafelter</H4>
		<P>Txt - Body text - Brødtekst</P>
		<Span>Txt - Unstyled text</Span>
	</Unstyled>
</Canvas>

This more or less shows what I really want. The "look" of a canvas, with no storybook styling inside, and then showing multiple stories in that "box". In this case:

[mdaoust-sidlee]

Thanks @mdaoust-sidlee, I've fixed it in #20803, should be released in the next couple of days.

@JReinhold, Thank you so much for your help on these various problems. A non-story Canvas on the root of the mdx file now work perfectly, but here's an example of an implementation that is still problematic. Wrapping the <Canvas> with any tags (like a div or a section) and it still fall into the No primary story defined for docs entry error.

import { Meta, Canvas } from '@storybook/addon-docs';

<Meta title="Documentation/Foundations/Color" />

<section>
  <Canvas>
    <h2>Some here</h2>
  </Canvas>
</section>

[JReinhold]

Wrapping the <Canvas> with any tags (like a div or a section) and it still fall into the No primary story defined for docs entry error.

import { Meta, Canvas } from '@storybook/addon-docs';

<Meta title="Documentation/Foundations/Color" />

<section>
  <Canvas>
    <h2>Some here</h2>
  </Canvas>
</section>

I'm sorry @mdaoust-sidlee I'm having trouble reproducing this, it works fine when I write the code in your example. Could you create a minimal reproduction, maybe in a separate issue?

[JReinhold]

I mostly just care about the border/look of the Canvas, not the source and features like that - so I'd be completely OK with not using Canvas but something else. It would be even better if that "something" had unstyled set on it.

Thanks for the feedback @Alxandr. It sounds like you just want the styling and don't really care for the Canvas functionality. In that case you can easily build a component with that styling yourself, and use everywhere in your MDX files.

Either by building a React component:

export const StoryContainer = (props) => {
  return <div className="sb-unstyled" style={{ nice border and padding...}} {...props} />
}

or by defining a CSS class that you can use directly in MDX:

<div className="sb-unstyled story-container">
  <H1 .../>
  <H2 .../>
</div>

[Alxandr]

@JReinhold yes. I looked into doing that first, but I wanted it to look the same as the actual canvases I used. And looking at the code, there's quite a bit involved in getting the same style as the builtin blocks:

• https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/components/BlockBackgroundStyles.tsx#L3
• https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/components/Preview.tsx#L51

I guess what I really would want is a block that has this "preview" view, as just a simple styled component.

[tlthiem]

I think this is still bugged with

import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';

[SSShooter]

For someone still face the problem Did you forget to use <Meta>?, place Meta tag before other tags like Title, Primary 😂

[timvandenhof]

Seems to work fine for Title but not for Subtitle yet. Stacktrace still shows storyById is called from the Subtitle2 component.

import { Meta, Title, Subtitle } from '@storybook/blocks';

<Meta title='Introduction' />
<Title>Title test</Title>
<Subtitle>Sub title test</Subtitle>

Error: No primary story defined for docs entry. Did you forget to use `<Meta>`?

[tmeasday]

Looks like Title and Subtitle need to be updated to use useOf, similar to Description:

storybook/code/ui/blocks/src/blocks/Description.tsx

Line 133 in 47446f4

const resolvedOf = useOf(of || 'meta');

If someone wants to open a new ticket or even send a PR, I'll take a look.

For someone still face the problem ... Primary

Primary doesn't make sense for an unattached page, surely? What would it render?

[JReinhold]

FYI we already have an issue open to update the remaining doc blocks here: #22490

[floroz]

The Source blocks is also still bugged on 7.1.0

Is there anyway to integrate into MDX third party custom components like https://github.com/rajinwonderland/react-code-blocks ?

[axelboc]

I'm running into this issue again with Canvas after upgrading to Storybook 8.

I'm just trying to wrap a piece of JSX in a Canvas inside a documentation-only MDX file. I've tried importing Canvas and Meta from @storybook/addon-docs and from @storybook/blocks (I tried all possible import combinations) but in all cases I get the same error: "No primary story defined for docs entry. Did you forget to use <Meta>?". Same if I don't use Meta at all and let the title be inferred from the first heading.

[Sanderand]

I'm having the same issue after upgrading to v8. Should this issue be reopened or should we raise a new one?

[json-derulo]

I ran into this issue after auto-migrating to the new MDX+CSF format. In v7, I used docs-only stories like the following:

import { ArgsTable, Description, Meta } from '@storybook/addon-docs';
import { MyComponent } from './my.component';

<Meta title="My Component" component={MyComponent} />
<Description />
<ArgsTable />

They were auto-migrated to the following, which produces runtime errors:

import { Controls, Description, Meta } from '@storybook/blocks';
import { MyComponent } from './my.component';

<Meta title="My Component" component={MyComponent} />
<Description />
<Controls />

I got it working again by changing from Controls to ArgTypes and passing the component in the individual blocks rather than in the Meta block:

import { ArgTypes, Description, Meta } from '@storybook/blocks';
import { MyComponent } from './my.component';

<Meta title="My Component" />
<Description of={MyComponent} />
<ArgTypes of={MyComponent} />

[JanderSilva-Acerta]

Any updates on this issue? I can't upgrade to Storybook 8 because my project doesn't support node.js 18 yet.