MDX Bundler Example

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.