compileMdx() and MDXRemote for Remote Content

Nextra processes MDX files at the webpack/Turbopack build level for local content, but sometimes you need to compile and render MDX that is fetched at request time — from a CMS, a GitHub repository, or a database. The compileMdx() function and MDXRemote component together provide a server-side compilation pipeline and a client-ready renderer for exactly this use case.

compileMdx()

Compiles a raw MDX string into serialised JavaScript that can be evaluated at runtime. The function runs the full Nextra remark/rehype/recma pipeline (GFM, syntax highlighting, front-matter extraction, smart quotes, etc.) and returns the resulting module code as a string.

import { compileMdx } from 'nextra/compile'

async function compileMdx(
  source: string,
  options?: Partial<CompileMdxOptions>
): Promise<string>

compileMdx always produces output in function-body format so that the compiled string can be evaluated safely inside MDXRemote without requiring a full module bundler at runtime.

Parameters

source

string

required

The raw MDX (or Markdown) source string to compile.

options

Partial<CompileMdxOptions>

Optional compilation settings. All fields are optional and mirror the corresponding options available in NextraConfig.

Show CompileMdxOptions fields

options.filePath

string

default:"''"

File path associated with the source string. Used in error messages and to resolve relative imports. Also determines format detection when mdxOptions.format is 'detect' — a .mdx extension produces MDX output; anything else produces Markdown output.

options.mdxOptions

MdxOptions

default:"{}"

MDX compiler options — the same shape as NextraConfig.mdxOptions. Accepts remarkPlugins, rehypePlugins, recmaPlugins, format, and rehypePrettyCodeOptions.

options.defaultShowCopyCode

boolean

Show a copy button on all code blocks by default (can be overridden per-block).

options.search

boolean | { codeblocks: boolean }

Controls Pagefind attribute injection on code blocks, matching the NextraConfig.search option.

options.staticImage

boolean

Optimise static image syntax via Next.js <Image>. Disabled by default for remote content since images may not be locally available.

options.latex

boolean | KatexConfig | MathjaxConfig

Enable LaTeX math rendering. Accepts the same values as NextraConfig.latex.

options.codeHighlight

boolean

default:"true"

Enable or disable Shiki-based syntax highlighting.

options.readingTime

boolean

Inject a readingTime key into the front matter object.

Additional HTML element names whose tags should be replaced by components defined in mdx-components.js. By default, Nextra replaces <details> and <summary>. Pass extra tag names here to extend that behaviour.

options.useCachedCompiler

boolean

Re-use an in-process cached compiler instance for the given format. Not recommended for remote content where each request may have different options.

options.isPageImport

boolean

default:"false"

Internal flag used by Nextra’s loader to signal that the file is a Next.js page entry point rather than an MDX import.

options.lastCommitTime

number

Unix timestamp of the file’s last git commit. Injected into front matter as timestamp when provided.

Return value

compileMdx returns a Promise<string> — the serialised JavaScript module body that MDXRemote evaluates to produce a React component.

The returned string is executable JavaScript. Do not compile untrusted user input without thorough sanitisation — treat it with the same caution you would give to eval().

MDXRemote

A React component that evaluates the string produced by compileMdx() and renders the resulting MDX content. It accepts custom component overrides and scope variables, making it easy to inject your own design-system components or dynamic data into remotely-fetched content.

import { MDXRemote } from 'nextra/mdx-remote'

Props

compiledSource

string

required

The serialised JavaScript string returned by compileMdx(). MDXRemote evaluates this string using Nextra’s evaluate helper and renders the default export as a React element.

components

Record<string, ComponentType>

An object mapping MDX element names to React components. These are merged with the components registered in your mdx-components.js file, so local overrides take precedence.

<MDXRemote
  compiledSource={compiledSource}
  components={{
    // Replace <Callout> in the MDX with your own component
    Callout: MyCallout,
    // Restyle all <h2> headings
    h2: ({ children }) => <h2 className="text-2xl font-bold">{children}</h2>,
  }}
/>

scope

object

An object whose keys become variables available inside the MDX expression scope. Useful for passing server-fetched data into the MDX content without embedding it directly in the source string.

<MDXRemote
  compiledSource={compiledSource}
  scope={{ version: '4.6.5', releaseDate: '2025-01-01' }}
/>

Full Remote Content Example

The following pattern fetches MDX from a remote URL, compiles it on the server, and renders it inside a Next.js App Router page. No build-time pre-processing is required.

app/remote/page.tsx

import { compileMdx } from 'nextra/compile'
import { MDXRemote } from 'nextra/mdx-remote'
import { Callout } from 'nextra/components'

export default async function RemotePage() {
  const source = await fetch(
    'https://raw.githubusercontent.com/shuding/nextra/main/README.md'
  ).then(r => r.text())

  const compiledSource = await compileMdx(source, {
    filePath: 'README.md',
  })

  return (
    <MDXRemote
      compiledSource={compiledSource}
      components={{ Callout }}
    />
  )
}

With scope variables and custom options

import { compileMdx } from 'nextra/compile'
import { MDXRemote } from 'nextra/mdx-remote'

interface Props {
  params: { version: string }
}

export default async function ChangelogPage({ params }: Props) {
  const mdxSource = await fetchChangelog(params.version)

  const compiledSource = await compileMdx(mdxSource, {
    filePath: `changelog/${params.version}.mdx`,
    defaultShowCopyCode: true,
    latex: false,
    mdxOptions: {
      rehypePrettyCodeOptions: {
        theme: 'github-dark',
      },
    },
  })

  return (
    <MDXRemote
      compiledSource={compiledSource}
      scope={{ version: params.version }}
    />
  )
}

async function fetchChangelog(version: string): Promise<string> {
  const res = await fetch(`https://api.example.com/changelog/${version}`)
  if (!res.ok) throw new Error(`Changelog not found: ${version}`)
  return res.text()
}

For best performance, cache the result of compileMdx() with Next.js unstable_cache or React’s cache() when the source content doesn’t change on every request.

Relationship to Local MDX Processing

For MDX files inside your content/ or app/ directory, Nextra compiles them automatically at build time via the webpack/Turbopack loader — you do not need compileMdx(). Use this API only when the MDX source is not available on disk at build time.

Scenario	Approach
MDX files in `content/` or `app/`	Automatic — no action needed
MDX fetched from a CMS at request time	`compileMdx()` + `MDXRemote`
MDX from a GitHub repository	`compileMdx()` + `MDXRemote`
User-generated MDX content	`compileMdx()` + `MDXRemote` (sanitise first)

Core API

Docs Theme API

Blog Theme API

compileMdx() and MDXRemote for Remote Content

compileMdx()

Parameters

Return value

MDXRemote

Props

Full Remote Content Example

With scope variables and custom options

Relationship to Local MDX Processing

Build docs developers (and LLMs) love

Core API

Docs Theme API

Blog Theme API

Documentation Index

​compileMdx()

​Parameters

​Return value

​MDXRemote

​Props

​Full Remote Content Example

​With scope variables and custom options

​Relationship to Local MDX Processing

Build docs developers (and LLMs) love

compileMdx()

Parameters

Return value

MDXRemote

Props

Full Remote Content Example

With scope variables and custom options

Relationship to Local MDX Processing