How to built a static site React Router v7 + MDX

Miguel Quintal — Fri, 20 Jun 2025 20:09:57 +0000

Tired of overcomplicated static site generators? Want to build your docs, blog, or site using just React Router v7 + MDX? Meet react-router-mdx — a small but powerful tool to generate static web sites. Check out our demo page

🧠 Why react-router-mdx?

Well, it keeps the process of creating static web pages based on MDX simple. No need for vite plugins and other dependencies. You just need to install it, setup where your MDX files are and viola!

That is where react-router-mdx comes in:

🔥 Automatic MDX route generation from a folder and file naming

🧩 Fully compatible with React Router v7 (Framework mode)

🛠️ Minimal setup — no custom compiler or extra dependencies

📦 SSR/Pre-rendering using react-router build

🚀 Installation

Make sure you're using React Router v7 (Framework mode). Once you have generated the React Router project your project's folder structure should look like:

my-amazing-webpage/
├── public/
├── app/
│   ├── home/
│   ├── routes/
│   │   └── home.tsx
│   ├── root.tsx
│   ├── routes.tsx
│   └── app.css
├── .gitignore
├── package.json
├── react-router.config.ts
├── tsconfig.json
└── vite.config.ts

Using yarn

yarn add react-router-mdx

Using npm

npm install react-router-mdx

🛠️ Set it up

1- Change your react-router.config.ts to init the and provide the pre-rendered paths.

Your react-router.config.ts should look like:

import type { Config } from "@react-router/dev/config";
import { init } from "react-router-mdx/server";


const mdx = init({ path: "posts" });

export default {
  ssr: true,
  async prerender() {
    return ["/", ...(await mdx.paths())];
  },
} satisfies Config;

The path passed to the init should the folder where you'll keep your MDX files.

2- Create hello-world.mdx file under posts directory:

posts/
└─ hello-world.mdx

posts/hello-world.mdx

---
title: hello world title
---
# hello world

This is a hello World mdx file

3- Add MDX routes to your app/routes.ts

import { index } from "@react-router/dev/routes";
import { routes } from 'react-router-mdx/server'

export default [
    index("routes/home.tsx"),
    ...routes("./routes/post.tsx")
]

4- Add MDX routes to your app/routes/posts.ts

import { loadMdx } from 'react-router-mdx/server'
import { useMdxComponent } from "react-router-mdx/client"
import type { Route } from "./+types/post";

export const loader = async ({ request }: Route.LoaderArgs) => {
  return loadMdx(request)
}

export default function Home() {
  const Component = useMdxComponent()
  return (
    <Component />
  );
}

Now if you run yarn dev you should have the page based on posts/hello-world.mdx on http://localhost:/posts/hello-world

🙌 Conclusion

If you're building a React Router v7-based site and want Markdown + React support with minimal friction, give react-router-mdx a shot. It's ideal for:

📚 Documentation sites

📝 Personal blogs

🧪 Component previews / style guides

Let me know what you build with it — contributions and feedback welcome!

DEV Community: Miguel Quintal

How to built a static site React Router v7 + MDX

🧠 Why react-router-mdx?

🚀 Installation

🛠️ Set it up

🙌 Conclusion