DEV Community

Cover image for How to built a static site React Router v7 + MDX
Miguel Quintal
Miguel Quintal

Posted on

How to built a static site React Router v7 + MDX

#react #reactrouter #mdx

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
Enter fullscreen mode Exit fullscreen mode

Using yarn

yarn add react-router-mdx
Enter fullscreen mode Exit fullscreen mode

Using npm

npm install react-router-mdx
Enter fullscreen mode Exit fullscreen mode

🛠️ 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;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

posts/hello-world.mdx

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

This is a hello World mdx file
Enter fullscreen mode Exit fullscreen mode

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")
]
Enter fullscreen mode Exit fullscreen mode

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 />
  );
}
Enter fullscreen mode Exit fullscreen mode

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!

Top comments (0)