{"id":20200,"library":"mdx-loader","title":"mdx-loader","description":"A batteries-included webpack loader for converting Markdown files into React components using MDX. Version 3.0.2 (latest) builds on mdx-js/mdx to provide emoji support (remark-emoji), automatic image embedding (remark-images), heading IDs (remark-slug), Prism.js syntax highlighting (rehype-prism), front matter export (gray-matter), table of contents (mdx-table-of-contents), and typographic improvements (remark-textr). Released as part of the mdx-util monorepo, it offers a zero-config experience for Webpack projects and can also be used inline with create-react-app via webpack loader syntax. Releases are infrequent; the loader uses MDX v1 and has not been updated for MDX v2, which is a breaking change. Key differentiator: all-in-one setup without needing separate remark/rehype plugins.","status":"maintenance","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/frontarm/mdx-util","tags":["javascript","mdx","loader","webpack-loader"],"install":[{"cmd":"npm install mdx-loader","lang":"bash","label":"npm"},{"cmd":"yarn add mdx-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdx-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"mdx-loader produces ES2015 code and must be chained with babel-loader for browser compatibility.","package":"babel-loader","optional":false},{"reason":"Core MDX compiler used to transform Markdown to JSX.","package":"@mdx-js/mdx","optional":false}],"imports":[{"note":"Default export is a React component. ESM-only due to webpack loader chain; CJS require not supported directly.","wrong":"const Component = require('./doc.mdx')","symbol":"default","correct":"import Component from './doc.mdx'"},{"note":"Named export for front matter object; not a default export.","wrong":"import frontMatter from './doc.mdx'","symbol":"frontMatter","correct":"import { frontMatter } from './doc.mdx'"},{"note":"Named export for table of contents tree; available when loader processes the file.","wrong":"","symbol":"tableOfContents","correct":"import { tableOfContents } from './doc.mdx'"}],"quickstart":{"code":"// webpack.config.js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.mdx?$/,\n        use: ['babel-loader', 'mdx-loader']\n      }\n    ]\n  }\n};\n\n// Component.js\nimport React from 'react';\nimport Doc, { frontMatter, tableOfContents } from './doc.mdx';\n\nexport default function MyPage() {\n  return (\n    <div>\n      <h1>{frontMatter.title}</h1>\n      <Doc />\n      <pre>{JSON.stringify(tableOfContents, null, 2)}</pre>\n    </div>\n  );\n}","lang":"javascript","description":"Webpack configuration to process .mdx files with mdx-loader and babel-loader, and a React component importing the MDX document, its front matter, and table of contents."},"warnings":[{"fix":"Use a different loader like @mdx-js/loader, or stay on MDX v1.","message":"The package is not compatible with MDX v2. Do not use with @mdx-js/mdx@^2.","severity":"breaking","affected_versions":"^2.0.0 || ^3.0.0"},{"fix":"Migrate to @mdx-js/loader or next-mdx-remote for newer MDX features.","message":"The package has not been updated since 2020; consider alternatives like @mdx-js/loader for new projects.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure babel-loader is installed and configured (e.g., @babel/preset-env).","message":"Requires babel-loader in the chain; output is ES2015 and must be transpiled for older browsers.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Add `import 'prismjs/themes/prism-tomorrow.css'` in your app entry.","message":"Syntax highlighting only works if you import a Prism stylesheet manually.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add { test: /\\.mdx$/, use: ['babel-loader', 'mdx-loader'] } to module.rules.","cause":"Webpack is missing the rule for .mdx files or the loader chain is incorrect.","error":"Module parse failed: Unexpected token (14:9). You may need an appropriate loader to handle this file type."},{"fix":"Run `npm install --save-dev @mdx-js/mdx`","cause":"@mdx-js/mdx is a required peer dependency not installed.","error":"Cannot find module '@mdx-js/mdx'"},{"fix":"Ensure the markdown file has YAML front matter delimited by '---'. Also verify that mdx-loader is in the webpack config.","cause":"The file does not contain front matter, or the loader is not processing it correctly.","error":"export 'frontMatter' (imported as 'frontMatter') was not found in './doc.mdx'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}