next-mdx-remote-client

The author of next-mdx-remote-client maintains a variety of plugins for the Unified/Remark/MDX ecosystem that can be used to extend Markdown processing. These include Remark plugins for content structure, Rehype plugins for HTML transformation, and Recma plugins specifically designed to improve MDX compatibility in Next.js applications.

### Remark Plugins
- `remark-flexible-code-titles` (code block titles/containers)
- `remark-flexible-containers` (custom containers)
- `remark-ins` (ins element)
- `remark-flexible-paragraphs` (custom paragraphs)
- `remark-flexible-markers` (custom mark element)
- `remark-flexible-toc` (table of contents via Vfile.data)
- `remark-mdx-remove-esm` (remove import/export statements)
- `remark-mdx-remove-expressions` (remove MDX expressions in {})

### Rehype Plugins
- `rehype-pre-language` (language info on pre elements)
- `rehype-highlight-code-lines` (line numbers and highlighting)
- `rehype-code-meta` (copy meta to properties)
- `rehype-image-toolkit` (enhanced image/media handling)

### Recma Plugins
- `recma-mdx-escape-missing-components` (default missing components to `() => null`)
- `recma-mdx-change-props` (renames `props` to `_props` for safer expression usage in Next.js)
- `recma-mdx-change-imports` (converts relative asset imports to string URLs)
- `recma-mdx-import-media` (converts media paths to import declarations)
- `recma-mdx-import-react` (ensures React runtime availability in compiled MDX)
- `recma-mdx-html-override` (override raw HTML via MDX components)
- `recma-mdx-interpolate` (enable interpolation in link/image attributes)

When migrating from next-mdx-remote to next-mdx-remote-client in the Next.js Pages Router:

1. Update Component: Replace <MDXRemote /> with <MDXClient />.
2. Update Imports: Use next-mdx-remote-client/csr for the client-side component.
3. Update serialize function:
   • It now accepts a single object argument instead of multiple positional arguments.
   • The rsc parameter has been removed.
   • Generic type parameters are now passed in the order <Frontmatter, Scope> (reversed from the old version).
   • It now returns an error object in the result.
4. Lazy Hydration: Instead of the lazy prop, use the hydrateLazy function or the <MDXClientLazy /> component.

// For "pages" router, it is a client component
- import { MDXRemote } from "next-mdx-remote"; 
+ import { MDXClient } from "next-mdx-remote-client/csr"; 

<MDXClient
  compiledSource={compiledSource}
  frontmatter={frontmatter}
  scope={scope}
  components={components}
+ onError={onError}
/>

When migrating from next-mdx-remote to next-mdx-remote-client in the Next.js App Router, follow these key changes:

1. Update Imports: Change next-mdx-remote/rsc to next-mdx-remote-client/rsc.
2. Use evaluate instead of compileMDX: The evaluate function replaces compileMDX. It supports two generic type parameters: <Frontmatter, Scope> (note the order change). It returns content, frontmatter, scope, mod, and error.
3. Error Handling: Use the onError prop on the <MDXRemote /> component to handle errors gracefully.
4. Component Naming: In the App Router, continue using <MDXRemote /> (which is a Server Component).

- import { MDXRemote } from 'next-mdx-remote/rsc'
+ import { MDXRemote } from 'next-mdx-remote-client/rsc'
+ import { ErrorComponent } from '../components'

export default function Home() {
  return (
    <MDXRemote
      source={`# Hello`}
+     onError={ErrorComponent}    
    />
  )
}

When migrating from next-mdx-remote to next-mdx-remote-client in a Next.js Pages Router project, you must update your imports and change how the serialize function is called.

Key changes:

1. Imports: Change next-mdx-remote to next-mdx-remote-client and next-mdx-remote/serialize to next-mdx-remote-client/serialize.
2. Component: Replace <MDXRemote /> with <MDXClient />.
3. Serialization: The serialize function now expects an object containing the source string, rather than the string itself. Use serialize({ source }).
4. Error Handling: The source prop (the result of serialization) may now contain an error key. You should check for this before rendering to prevent crashes.

- import { serialize } from 'next-mdx-remote/serialize'
- import { MDXRemote } from 'next-mdx-remote'

+ import { serialize } from 'next-mdx-remote-client/serialize'
+ import { MDXClient } from 'next-mdx-remote-client'

export default function TestPage({ source }) {
+ if ("error" in source) {
+   return <ErrorComponent error={source.error} />;
+ }

  return (
    <div className="wrapper">
-     <MDXRemote {...source} components={components} />
+     <MDXClient {...source} components={components} />
    </div>
  )
}

export async function getStaticProps() {
  const source = 'Some **mdx** text'
- const mdxSource = await serialize(source)
+ const mdxSource = await serialize({source})
  return { props: { source: mdxSource } }
}

Because MDX compiles to executable JavaScript, rendering untrusted MDX can lead to Cross-Site Scripting (XSS) and Remote Code Execution (RCE).

Mitigation Strategies

1. Remove Dangerous Expressions: Use the remark-mdx-remove-expressions plugin at the remark stage to strip executable or dangerous MDX expressions (like JavaScript logic) before compilation.
2. Disable ESM Blocks: If you do not control the content, disable import and export declarations (mdxjsEsm) via MDX options to prevent unauthorized module loading.
3. Sanitize Input: Always treat MDX as executable code. If the source is not strictly trusted, apply sanitization or restrictions before passing it to the renderer.
4. Content Security Policy (CSP): If your site uses a strict CSP, you may need to allow unsafe-eval in your script-src policy, as the MDX runtime uses Reflect.construct (similar to eval) for evaluation. Be aware of the security implications of enabling unsafe-eval.

import remarkMdxRemoveExpressions from "remark-mdx-remove-expressions";

// Example: Removing dangerous expressions during compilation
{
  mdxOptions: {
    remarkPlugins: [
      [remarkMdxRemoveExpressions, { onlyDangerousExpressions: true }]
    ]
  }
}