The MDX Bundler Example is a Next.js boilerplate that demonstrates how to build a blog by bundling MDX files with the mdx-bundler library, loading them through getStaticProps or getServerSideProps.
What is the MDX Bundler Example?
This is a minimal example app, not a full production template, that shows how to integrate mdx-bundler, a library by Kent C. Dodds, into a Next.js project. It takes MDX files from a local folder, though they could come from a database or anywhere else, bundles them at build time or request time, and renders them as React components in a blog-like page. The example also integrates next-remote-watch, a tool from HashiCorp that lets Next.js watch files outside the pages folder, so changes to MDX files trigger live reload without restarting the dev server.
Key Features
- mdx-bundler integration — Uses the mdx-bundler library to compile MDX source into executable JavaScript code that can be rendered with getMDXComponent.
- Flexible data sourcing — MDX content is loaded from a local folder in the example, but the same pattern supports content fetched from a database or any other backend.
- getStaticProps / getServerSideProps — Demonstrates loading MDX content at build time or per request using Next.js data-fetching functions.
- Live reload with next-remote-watch — Uses HashiCorp's next-remote-watch library to watch MDX files outside the pages directory and reload the browser on changes, run via npm run dev:watch or yarn dev:watch.
- Conditional custom components — Shows how to use next/dynamic to conditionally load infrequently used MDX components only on the pages that need them, keeping the main bundle smaller.
- Component name detection — The example checks raw MDX source for component names with a regex before bundling, passing the list of needed components to the page so it can decide which to dynamically import.
Who is it for?
- Next.js developers who want to see a working integration of mdx-bundler without pulling in a full CMS.
- Blog builders who need a minimal reference for rendering local Markdown/MDX files with hot reload.
- Library maintainers evaluating mdx-bundler as a bundling strategy and looking for a pattern to conditionally load heavy components.
What can you do with it?
- Create a simple blog: Place authored MDX files in a folder and have them rendered as blog posts with support for JSX and custom components.
- Experiment with live reload: Run the dev:watch script to see MDX changes appear in the browser immediately, even though the files are not imported into the Next.js page graph.
- Optimize component loading: Follow the pattern to load heavy MDX components only on pages that use them, using next/dynamic.
How does the example work?
The example stores MDX files in a local directory. During data fetching, it reads the source, optionally scans for special component names with a regex, and calls bundleMDX to produce JavaScript code. That code is passed to the page component, which uses getMDXComponent to render it. When running with npm run dev:watch, next-remote-watch monitors the external content folder and triggers a reload on change.
FAQ
Is the MDX Bundler Example a production-ready template?
No, it is a minimal example intended to demonstrate the mdx-bundler workflow, not a full-featured blog theme.
How do I start the example?
Use npm run dev:watch or yarn dev:watch to enable live reload of MDX files outside the pages folder. The regular dev script does not watch external content.
Can the MDX content be loaded from a database?
Yes, the example notes that content could be loaded from a database instead of a local folder; only the data fetching step changes.
Why use next-remote-watch instead of the default dev script?
The next-remote-watch library relies on undocumented Next.js APIs, so it is not a drop-in replacement for the default dev script; the example keeps both scripts available.
