Using a custom MDX file for the AutoDocs Page Template causes a build error when running tests

[brian-patrick-3]

Describe the bug

Our project uses a custom DocumentationTemplate.mdx file. The storybook and build-storybook commands work with no issue. When I try to run the tests with this addon, a build error is thrown. Removing the custom docs page template allows the tests to run.

Error

Module parse failed: Unexpected token (12:0)        
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
| import { UsageExample } from './usageBlock';      
|
> <Meta isTemplate />
|
| <Title />
=> Failed to build the preview

Template file

import {
  Meta,
  Title,
  Subtitle,
  Description,
  Primary,
  Controls,
  Stories,
} from '@storybook/blocks';
import { UsageExample } from './usageBlock';

<Meta isTemplate /> {/* This is where it errors out */}

<Title />

<Subtitle />

<Description />

<UsageExample />

## Primary Example

<Primary />

## Properties Reference

<Controls />

## Additional Stories

<Stories />

preview.js

import DocumentationTemplate from './DocumentationTemplate.mdx';
import { setCustomElementsManifest } from '@storybook/web-components';
import customElements from '../custom-elements.json';

export default {
  parameters: {
    docs: {
      page: DocumentationTemplate,
    },
    backgrounds: { disable: true },
  },
};

setCustomElementsManifest(customElements);

To reproduce

Here is a link to a branch on our repo where the error can be reproduced: https://github.com/kyndryl-design-system/shidoka-foundation/tree/docs/visual-testing

Environment

Latest versions of storybook and this addon.

[shilman]

@brian-patrick-3 thanks so much for filing. this looks like a corner case. in order to speed up Storybook's build process in the visual test addon, we run a "test" build which is like a normal build but with a bunch of features turned off. You can try manually re-enabling them. I'm guessing the MDX one specifically might solve it:

https://storybook.js.org/docs/api/main-config-build#testdisablemdxentries

[y-okt]

@shilman Hello, I also encountered the same situation. Even after making disableMDXEntries: true, still the same error happens (sample repository). This situation seems to be happening when a mdx file is called in a TypeScript file.

Example:

import mdx from "./Button.mdx";

const meta = {
  title: "Example/Button",
  component: Button,
  parameters: {
    layout: "centered",
    docs: {
      page: mdx, // this seems to be causing the error
      iframeHeight: 100,
    },
    viewMode: "docs",
  },
} satisfies Meta<typeof Button>;

Thank you.

[rChaoz]

Same issue here. I'm using Svelte, and the error log is a bit different:

Error: [storybook:external-globals-plugin] Parse error @:10:145
file: [...]/src/stories/Card.mdx
    at parse (.\node_modules\es-module-lexer\dist\lexer.cjs:1:402)
    at Object.transform (.\node_modules\@storybook\builder-vite\dist\index.js:55:3377)
    at file:///[...]/node_modules/rollup/dist/es/shared/node-entry.js:19579:40

I also have the import mdx from './file.mdx', which is then used withdocs: { page: mdx }, andtest: { disableMDXEntries: false }` does not fix the error.

Perhaps as a workaround, is there a way to convince chromatic to do a normal (non-test) build?

Also, Sev3 seems a little low for this bug - while it's only an annoyance when it comes to the whole Chromatic service, as it only requires you to manually run yarn chromatic, when it comes to this plugin alone, it makes it completely unusable for anyone importing mdx files - which I think is a significant part of the userbase.

[rChaoz]

Possibly related: https://github.com/storybookjs/storybook/issues/25114

[JReinhold]

I think MDX files need addon-docs to be enabled, so the test.disabledAddons setting should help instead:

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y',
  ],
  build: {
    test: {
      disabledAddons: [], // 👈 don't disable any addons
    },
  },
};

export default config;

Possible fixes we could do:

1. Be smart about detecting MDX file imports in the preview and enable addon-docs if they are there - this sounds like a lot of effort and static analysis complexity
2. Have an "mdx imports are no-ops" builder plugin/loader when in test mode. Making the import not crash but just do nothing instead.
3. Improve the build-time error to describe how to enable addon-docs. (this might solve general confusions about MDX, not just when it breaks in test/VTA mode)
4. Document this shortcoming in the VTA docs.