next-mdx-remote-client

A robust Next.js newsletter Next.js Weekly is sponsoring me 💖

An outstanding Git-based CMS Outstatic is also sponsoring me 💖

A warm thanks 🙌 to @ErfanEbrahimnia, @avitorio, @recepkyk, and @LSeaburg for the support 💖

---

[![npm version][badge-npm-version]][url-npm-package] [![npm downloads][badge-npm-download]][url-npm-package] [![publish to npm][badge-publish-to-npm]][url-publish-github-actions] [![code-coverage][badge-codecov]][url-codecov] [![type-coverage][badge-type-coverage]][url-github-package] [![typescript][badge-typescript]][url-typescript] [![license][badge-license]][url-license]

next-mdx-remote-client is recommended in the Next.js official documentation.

[!IMPORTANT] If you are using react18, use ver.1 of next-mdx-remote-client, currently v1.1

If you are using react19, use ver.2 of next-mdx-remote-client, currently v2.1

The both serve the same features and APIs. I am going to maintain both.

next-mdx-remote-client is a wrapper of @mdx-js/mdx for nextjs applications in order to load MDX content. It is a fork of next-mdx-remote.

See some blog applications in which next-mdx-remote-client is used:

• for a app router demo application visit source code or living web site,
• for a pages router demo application visit source code or living web site,
• for a testing application which uses both app and pages router, visit source code or living web site.

Why next-mdx-remote-client ?

I started to create next-mdx-remote-client in line with the mindset of @mdx-js/mdx in early 2024 considering next-mdx-remote had not been updated for a long time, and finally, a brand new package emerged.

next-mdx-remote-client serves as a viable alternative to next-mdx-remote having more features.

I would like to highlight some main features:

• It supports MDX version 3.
• It provides well designed components and functions for both "pages" router and "app" router, which completely isolated from eachother.
• It provides internal error handling mechanism.
• It supports import statements and export statements in MDX source, which can be disabled as well.
• Creating table of contents (TOC) is so easy since it supports passing vfile.data into the scope.
• You can get frontmatter without compiling the source for example for listing articles/posts via getFrontmatter.
• It exports some components and types from @mdx-js/mdx so as you don't need to install.

Let's compare the features of next-mdx-remote and next-mdx-remote-client.

| Features | next-mdx-remote | next-mdx-remote-client | | :---------------------------------------------------------- | :-----------------: | :----------------------: | | support MDX version 3 | ✅ | ✅ | | ensure internal error handling mechanism in app router | ❌ | ✅ | | ensure internal error handling mechanism in pages router | ❌ | ✅ | | support export-from-MDX in app router | ❌ | ✅ | | support export-from-MDX in pages router | ❌ | ✅ | | support import-into-MDX in app router | ❌ | ✅ | | support import-into-MDX in pages router | ❌ | ❌ | | get frontmatter and mutated scope in app router | ❌ | ✅ | | get frontmatter and mutated scope in pages router | ✅ | ✅ | | support options for disabling imports and exports in MDX | ✅ | ✅ | | support passing vfile.data into the scope | ❌ | ✅ | | provide utility for getting frontmatter without compiling | ❌ | ✅ | | expose MDXProvider from @mdx-js/mdx | ❌ | ✅ | | provide option for disabling parent MDXProvider contexts | ❌ | ✅ | | expose the necessary types from mdx/types | ❌ | ✅ | | injects React instance into runtime options | ❌ | ✅ |

[!IMPORTANT] You will see a lot the abbreviatons csr and rsc. Pay attention to the both are spelled backwards.

csr stands for "client side rendering" which is related with pages router
rsc stands for "react server component" which is related with app router

General considerations about development

• It is ESM only package
• Needs react version 19.1+, works with next@15 and next@16 versions (tested)
• Needs node version 20.9.0+ in line with Next.js does
• Vitest is used instead of jest for testing
• Rollup is removed for bundling
• Test coverage is 100%
• Type coverage is 100%
• The parts client side (csr) and server side (rsc) are completely isolated from each other
• Exported a small utility to get frontmatter without compiling the source
• All functions take named parameters
• Supports import statements and export statements in MDX
• Export statements in MDX work for both app and pages router
• Import statements in MDX work for only app router

[!IMPORTANT] Imported modules in MDX with relative path should be transpiled into javascript before or during build process, otherwise will not work. I believe the community can find a solution to import reqular .jsx or .tsx modules into MDX. With the support of the next/mdx, it is viable to import .mdx into MDX, but not tested yet.

Installation

This package is ESM only, requires Node.js (version 18.18+).

# in general
npm install next-mdx-remote-client

# specifically for react18 users
npm install next-mdx-remote-client@^1

# specifically for react19 users
npm install next-mdx-remote-client@^2

or

yarn add next-mdx-remote-client

[!WARNING]
next-mdx-remote users may follow the migration guide.

Initial Security Concerns

Before diving into next-mdx-remote-client, it’s important to highlight the security risks associated with rendering MDX content.

Because MDX supports JavaScript expressions, it introduces serious security considerations. If the content is not fully trusted and controlled, it can enable cross-site scripting (XSS) attacks and even lead to remote code execution (RCE). In the worst-case scenario, attackers could steal sensitive data, inject malicious scripts, install malware, or compromise your server.

Never render user-supplied MDX without proper sanitization.

MDX provides three powerful constructs: JSX syntax, JavaScript expressions, and ESM blocks (mdxjsEsm) such as import and export. next-mdx-remote-client provides options to disable ESM blocks (mdxjsEsm). However, it does not take responsibility for securing MDX content itself, as it operates purely at the rendering layer. Content sanitization and JS expression control should be handled earlier in the processing pipeline (e.g., at the remark/recma/compilation stage).

If you do not have full control over the MDX source, you should at minimum strip dangerous JavaScript expressions before rendering. A recommended approach is to use the remark plugin remark-mdx-remove-expressions, which removes executable/dangerous MDX expressions at the syntax level.

For further security concerns you can visit Security section.

The package's exported subpaths

The main entry point / also refers to /csr subpath.

// main entry point, which is related "pages" router
import /* */ from "next-mdx-remote-client";

// isolated subpath for the "serialize" function
import /* */ from "next-mdx-remote-client/serialize";

// sub entry point related with "pages" router
import /* */ from "next-mdx-remote-client/csr";

// sub entry point related with "app" router
import /* */ from "next-mdx-remote-client/rsc";

// isolated subpath for the utils
import /* */ from "next-mdx-remote-client/utils";

The part associated with Next.js app router

Go to the part associated with Next.js pages router

next-mdx-remote-client exposes evaluate function and MDXRemote component for "app" router.

import { evaluate, MDXRemote } from "next-mdx-remote-client/rsc";

[!TIP] If you need to get the exports from MDX --> use evaluate
If you don't need --> use MDXRemote

If you need to get the **front