storybook-addon-vue-mdx facilitates the integration and rendering of Vue 3 components directly within MDX documentation files in Storybook. The current stable version is 3.0.0, which targets Storybook v10. This addon's release cadence appears to be closely tied to major Storybook releases, requiring updates to support newer Storybook versions. Its primary differentiator is enabling Vue component usage in an MDX context, leveraging `veaury` to bridge the Vue/React rendering environments within Storybook's predominantly React-based MDX compiler. It supports customization of the Vue app context via Storybook globals, allowing for the registration of Vue plugins or other app-level configurations. While powerful, it has limitations such as requiring local imports of components and a known bug affecting initial local page loads for MDX files with Vue components.
npm install storybook-addon-vue-mdxVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to install `storybook-addon-vue-mdx`, configure it in Storybook's `main.js`, and then use a Vue component directly within an MDX documentation file, including basic component definition.
Upgrade your Storybook project to version 10 or later. For Storybook 7, use `storybook-addon-vue-mdx@0.1.5`. For Storybook 8, use `storybook-addon-vue-mdx@1.0.6`.
Ensure your Storybook and React versions align with the specific `storybook-addon-vue-mdx` version you are using. Refer to the release notes for version-specific compatibility.
Refresh the browser tab once. The page should load successfully on the second attempt. This bug is not reported to occur in production builds.
Always use relative or alias paths to import Vue components directly into your `.mdx` files where they are consumed.
Review your project's build processes and ensure compatibility with modern build targets. If using yarn or npm, ensure dependencies are resolved correctly. Update your local package manager if necessary to match pnpm as indicated in the project's development scripts.
Ensure that the `globals` export in `.storybook/preview.js` includes `vueMdx` with the `beforeVueAppMount` function, if you intend to customize the Vue app context. Example:
```javascript
// .storybook/preview.js
const globals = {
vueMdx: {
beforeVueAppMount(app) {
// your custom logic here
},
},
};
export default {
globals,
};
```Verify that `storybook-addon-vue-mdx` is correctly added to the `addons` array in your `.storybook/main.js` file. Also, double-check the Vue JSX syntax used for your components and slots as documented by Vue.
Ensure that the path to your Vue component in the MDX `import` statement is correct and that the component itself is properly exported (e.g., using `defineComponent` or `<script setup>`). Make sure Storybook's `builder-vite` is correctly configured and handling `.vue` files.