{"id":12082,"library":"storybook-addon-vue-mdx","title":"Storybook Addon for Vue Components in MDX","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/Sidnioulz/storybook-addon-vue-mdx","tags":["javascript","storybook-addon","organize","documentation","vue","mdx","typescript"],"install":[{"cmd":"npm install storybook-addon-vue-mdx","lang":"bash","label":"npm"},{"cmd":"yarn add storybook-addon-vue-mdx","lang":"bash","label":"yarn"},{"cmd":"pnpm add storybook-addon-vue-mdx","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for MDX documentation features in Storybook.","package":"@storybook/addon-docs","optional":false},{"reason":"Typically used as the builder for Storybook projects with Vue.","package":"@storybook/builder-vite","optional":false},{"reason":"Veaury, used internally, requires React and React DOM for its bridging functionality, even when rendering Vue components.","package":"react","optional":false},{"reason":"Veaury, used internally, requires React and React DOM for its bridging functionality, even when rendering Vue components.","package":"react-dom","optional":false},{"reason":"Core Storybook dependency, the addon integrates with its ecosystem.","package":"storybook","optional":false},{"reason":"The addon is specifically designed to render Vue 3 components.","package":"vue","optional":false}],"imports":[{"note":"The addon is configured in `main.js` by listing its package name in the `addons` array. It does not export direct symbols for import in application code.","wrong":"import storybookAddonVueMdx from 'storybook-addon-vue-mdx';","symbol":"Addon Configuration","correct":"// .storybook/main.js\nexport default {\n  addons: ['storybook-addon-vue-mdx'],\n}"},{"note":"Vue components are imported directly into MDX files and used with Vue JSX syntax. This requires the MDX compiler to be configured by the addon.","symbol":"Vue Component in MDX","correct":"// Sample.mdx\nimport MyComponent from './path-to-components/MyComponent.vue'\n\n<MyComponent>bla bla</MyComponent>"},{"note":"Customizations for the Vue application instance (e.g., registering plugins) are passed via the Storybook `globals` object under the `vueMdx` key. The `beforeVueAppMount` function receives the Vue app instance.","symbol":"Customizing Vue App Context","correct":"// .storybook/preview.js\nconst globals = {\n  vueMdx: {\n    beforeVueAppMount(app) {\n      app.use(myCustomPlugin)\n    },\n  },\n}\n\nexport default {\n  globals,\n}"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\n\n// .storybook/main.js\nexport default {\n  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx|vue)'],\n  addons: [\n    '@storybook/addon-essentials',\n    '@storybook/addon-docs',\n    'storybook-addon-vue-mdx',\n  ],\n  framework: {\n    name: '@storybook/vue3-vite',\n    options: {},\n  },\n  docs: {\n    autodocs: 'tag',\n  },\n  // .storybook/preview.js\n  // For customizing Vue app context (optional)\n  // globals: {\n  //   vueMdx: {\n  //     beforeVueAppMount(app) {\n  //       app.use(yourVuePlugin);\n  //     },\n  //   },\n  // },\n};\n\n// src/components/MyButton.vue\n<template>\n  <button @click=\"onClick\">{{ label }}</button>\n</template>\n\n<script setup>\nimport { defineProps } from 'vue';\n\nconst props = defineProps({\n  label: { type: String, default: 'Click me' },\n});\n\nconst onClick = () => {\n  console.log('Button clicked!');\n};\n</script>\n\n// src/stories/MyButton.mdx\nimport { Meta, Story } from '@storybook/addon-docs';\nimport MyButton from '../components/MyButton.vue';\n\n<Meta title=\"Components/MyButton\" component={MyButton} />\n\n# MyButton\n\nThis is a custom button component.\n\n<MyButton label=\"Hello from MDX\" />\n\n<Story name=\"Default\">\n  <MyButton label=\"Story in MDX\" />\n</Story>","lang":"typescript","description":"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."},"warnings":[{"fix":"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`.","message":"Version 3.0.0 of `storybook-addon-vue-mdx` requires Storybook 10 as the minimal supported version. Previous versions will not be compatible.","severity":"breaking","affected_versions":"3.0.0"},{"fix":"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.","message":"Version 1.0.0 was a breaking change, porting the addon to support Storybook 8.2.4. Subsequent versions (1.0.6) targeted Storybook 8.5 and React 19.","severity":"breaking","affected_versions":"1.0.0"},{"fix":"Refresh the browser tab once. The page should load successfully on the second attempt. This bug is not reported to occur in production builds.","message":"A known bug exists when running Storybook locally where the initial page load of an MDX page with Vue components might crash. This is likely due to Storybook's preview file execution.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use relative or alias paths to import Vue components directly into your `.mdx` files where they are consumed.","message":"Components must be locally imported into MDX files. Remote imports or global component registration patterns may not be supported or have not been thoroughly tested.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"Version 2.0.0 included breaking changes related to build targets, security fixes (false positives), and a switch to pnpm for CI/CD workflow, potentially affecting local development setups relying on specific build behaviors or package managers.","severity":"breaking","affected_versions":"2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"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:\n```javascript\n// .storybook/preview.js\nconst globals = {\n  vueMdx: {\n    beforeVueAppMount(app) {\n      // your custom logic here\n    },\n  },\n};\nexport default {\n  globals,\n};\n```","cause":"The `vueMdx` global object or `beforeVueAppMount` property is not correctly defined in `.storybook/preview.js`.","error":"Cannot read properties of undefined (reading 'beforeVueAppMount')"},{"fix":"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.","cause":"The Storybook builder is not correctly configured to process Vue JSX within MDX, or the Vue component itself has invalid JSX syntax.","error":"Syntax Error: Cannot use JSX syntax in .mdx file with Vue components."},{"fix":"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.","cause":"The Vue component imported into the MDX file is not being correctly resolved or passed to the React rendering context, often due to an incorrect import path or module resolution issues.","error":"Invariant Violation: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports."}],"ecosystem":"npm"}