Better compilation errors for MDX stories

[PupoSDC]

Is your feature request related to a problem? Please describe

It's very frustrating debugging compilation errors in mdx stories.

For example, here is a story im working on:

import { useState } from 'react';
import {
  Meta,
  Story,
  Canvas,
  ArgsTable,
  Props,
} from '@storybook/addon-docs/blocks';
import Button from '../Button';

<Meta title="components/common/Button" component={Button} />

# Button

Generic button component to be used in our application.

<Canvas>
  <Story
    name="primary text"
    args={{ mode: 'text', children: 'primary text', color: 'primary' }}>
    {(args) => <Button {...args} />}
  </Story>
  <Story
    name="secondary text"
    args={{ mode: 'text', children: 'secondary text', color: 'secondary' }}>
    {(args) => <Button {...args} />}
  </Story>
  <Story
    name="disabled text"
    args={{ mode: 'text', children: 'disabled text', disabled: true }}>
    {(args) => <Button {...args} />}
  </Story>

  <Story
    name="primary outlined"
    args={{ mode: 'outlined', children: 'primary outlined', color: 'primary' }}>
    {(args) => <Button {...args} />}
  </Story>
  <Story
    name="secondary outlined"
    args={{
      mode: 'outlined',
      children: 'secondary outlined',
      color: 'secondary',
    }}>
    {(args) => <Button {...args} />}
  </Story>
  <Story
    name="disabled outlined"
    args={{ mode: 'outlined', children: 'disabled outlined', disabled: true }}>
    {(args) => <Button {...args} />}
  </Story>
</Canvas>

and here is the error im getting:

WARNING in ./src/components/common/__stories__/Button.stories.mdx
Module build failed (from ./node_modules/@mdx-js/loader/index.js):
SyntaxError: Unexpected token (16:10)
    at Object._raise (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:766:17)
    at Object.raiseWithData (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:759:17)
    at Object.raise (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:753:17)
    at Object.unexpected (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:8966:16)
    at Object.jsxParseElementAt (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:4670:24)
    at Object.jsxParseElement (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:4706:17)
    at Object.parseExprAtom (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:4713:19)
    at Object.parseExprSubscripts (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9844:23)
    at Object.parseUpdate (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9824:21)
    at Object.parseMaybeUnary (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9813:17)
    at Object.parseExprOps (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9683:23)
    at Object.parseMaybeConditional (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9657:23)
    at Object.parseMaybeAssign (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9620:21)
    at Object.parseExpressionBase (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9564:23)
    at /Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:9558:39
    at Object.allowInAnd (/Users/pupo/Dev/greator/personality-test-webapp/code/node_modules/@babel/parser/lib/index.js:11297:16)
 @ \.)(?=.)[^/]*?\.stories\.mdx)$ (./src sync ^\.(?:(?:^|\/|(?:(?:(?!(?:^|\/)\.).)*?)\/)(?!\.)(?=.)[^/]*?\.stories\.mdx)$) ./components/common/__stories__/Button.stories.mdx
 @ ./.storybook/generated-stories-entry.js

It's not very informative. Line 16 is the <canvas> element, and it's basically telling me there is an error somewhere between line 16-83.

Describe the solution you'd like

a better error log saying exactly the line where the mdx is broken.

Describe alternatives you've considered

The only debug workflow i have right now is to delete blocks of code one by one until i find the one that is broken (a method thats not even working for this particular snippet).

Are you able to assist to bring the feature to reality?

no. I don't think I have the skillz.

Keep up the great work!

[shilman]

This is an error from the MDX compiler, not from Storybook. Hopefully we can get better errors when v2 is released (mdx-js/mdx#1041), or even better yet, the MDX parser becomes more resilient to errors. Will definitely circle back on this.

[agrohs]

FWIW - I find w/ mdx many of those obtuse errors are just caused by an extra line break. I installed an MDX plugin for VSCode which helped to show the extra line breaks causing it to not be recognized as valid syntax.

[shilman]

Great tip @agrohs! ❤️

[stale]

Hi everyone! Seems like there hasn't been much going on in this issue lately. If there are still questions, comments, or bugs, please feel free to continue the discussion. Unfortunately, we don't have time to get to every issue. We are always open to contributions so please send us a pull request if you would like to help. Inactive issues will be closed after 30 days. Thanks!

[marians]

I just had a very weird debugging experience and would like to share it here.

This is the start of my file Colors.stories.mdx:

import { Box } from 'grommet';
import { Meta } from '@storybook/addon-docs/blocks';
import ColorSample from 'styles/stories/ColorSample';
import theme from 'styles/theme';

<Meta title='Display/Colors' />

# Colors

## Our main colors

<Preview>
  <Story name="Main">
    <ColorSample color={theme.colors.darkBlue} title='colors.darkBlue'>
      <p>Our reference dark blue. We derive many other shades from this color value.</p>
    </ColorSample>

    <ColorSample color={theme.colors.yellow1} title='colors.yellow1'>
      <p>Some yellow tone</p>
    </ColorSample>
  </Story>
</Preview>

This yielded the warning

WARNING in ./src/styles/stories/Colors.stories.mdx
Module build failed (from ./node_modules/@mdx-js/loader/index.js):
SyntaxError: Unexpected token (5:18)
    at Object._raise (/Users/marian/git/giantswarm/happa/node_modules/@babel/parser/lib/index.js:776:17)
    at Object.raiseWithData (/Users/marian/git/giantswarm/happa/node_modules/@babel/parser/lib/index.js:769:17)
    at Object.raise (/Users/marian/git/giantswarm/happa/node_modules/@babel/parser/lib/index.js:737:17)

and the according story Display/Colors was missing from the generated output. I was searching for anything suspicious in line 5, character 18, but failed. Line 5 is in fact empty.

Thanks to comment #12780 (comment) by @agrohs I tried removing the empty line between my two ColorSample blocks. And this in fact solved the problem.

It is strange though that if there is something in that line, e. g. a blank space, it doesn't fail. But it reproducible in the MDX playground even. https://mdxjs.com/playground/

If that is something everybody else working with MDX knows, we are fine. If not, maybe Storybook can somehow help to improve the experience here.

[shilman]

@marians we are waiting for MDXv2 to re-address this mdx-js/mdx#1041

[shilman]

Hey gang! A lot of you have been waiting a long time for MDXv2. I've released experimental support in Storybook 6.5 and would love your help to kick the tires. I've written up a short guide here and will update it with the latest as it stabilizes:

https://gist.github.com/shilman/6ff2d7e18db8846e8fc552fb432ae4f6

[ndelangen]

In storybook 7.0 beta the MDX2 is the new default, I'm closing this issue.