Skip to navigation
2 minutes read
By Titus Wormer

MDX on demand

This guide shows how to use @mdx-js/mdx to compile MDX on the server and run the result on clients. Some frameworks, such as Next.js and Remix, make it easy to split work between servers and clients. Using that it’s possible to for example do most of the work on demand on the server instead of at build time, then pass the resulting data to clients, where they finally use it.

This is similar to what people sometimes use mdx-bundler or next-mdx-remote for, but MDX also supports it.

Quick example

On the server:

server.js
import {compile} from '@mdx-js/mdx'

const code = String(await compile('# hi', {
  outputFormat: 'function-body',
  /* …otherOptions */
}))
// To do: send `code` to the client somehow.

(alias) function compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

Compile MDX to JS.

  • @param vfileCompatible MDX document to parse.
  • @param compileOptions Compile configuration (optional).
  • @return Promise to compiled file.
const code: string
var String: StringConstructor
(value?: any) => string

Allows manipulation and formatting of text strings and determination and location of substrings within strings.

(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

Compile MDX to JS.

  • @param vfileCompatible MDX document to parse.
  • @param compileOptions Compile configuration (optional).
  • @return Promise to compiled file.
(property) outputFormat?: "function-body" | "program" | null | undefined

Output format to generate (default: 'program'); in most cases 'program' should be used, it results in a whole program; internally evaluate uses 'function-body' to compile to code that can be passed to run; in some cases, you might want what evaluate does in separate steps, such as when compiling on the server and running on the client.

On the client:

client.js
import {run} from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'

const code = '' // To do: get `code` from server somehow.

const {default: Content} = await run(code, {...runtime, baseUrl: import.meta.url})

(alias) function run(code: {
    toString(): string;
}, options: RunOptions): Promise<MDXModule>
import run

Run code compiled with outputFormat: 'function-body'.

☢️ Danger: this evals JavaScript.

  • @param code JavaScript function body to run.
  • @param options Configuration (required).
  • @return Promise to a module; the result is an object with a default field set to the component; anything else that was exported is available too.
import runtime
const code: ""
(property) MDXModule.default: MDXContent

A functional JSX component which renders the content of the MDX file.

const Content: MDXContent

A functional JSX component which renders the content of the MDX file.

(alias) run(code: {
    toString(): string;
}, options: RunOptions): Promise<MDXModule>
import run

Run code compiled with outputFormat: 'function-body'.

☢️ Danger: this evals JavaScript.

  • @param code JavaScript function body to run.
  • @param options Configuration (required).
  • @return Promise to a module; the result is an object with a default field set to the component; anything else that was exported is available too.
const code: ""
import runtime
(property) baseUrl?: string | URL | null | undefined

Use this URL as import.meta.url and resolve import and export … from relative to it (optional, example: import.meta.url); this option can also be given at compile time in CompileOptions; you should pass this (likely at runtime), as you might get runtime errors when using import.meta.url / import / export … from otherwise.

The type of import.meta.

If you need to declare that a given property exists on import.meta, this type may be augmented via interface merging.

(property) ImportMeta.url: string

The absolute file: URL of the module.

Content is now an MDXContent component that you can use like normal in your framework (see § Using MDX).

More information is available in the API docs of @mdx-js/mdx for compile and run. For other use cases, you can also use evaluate, which both compiles and runs in one.

Note: MDX is not a bundler (esbuild, webpack, and Rollup are bundlers): you can’t import other code from the server within the string of MDX and get a nicely minified bundle out or so.

Next.js example

Some frameworks let you write the server and client code in one file, such as Next.

pages/hello.js
/**
 * @import {MDXModule} from 'mdx/types.js'
 * @import {Dispatch, SetStateAction} from 'react'
 */

import {compile, run} from '@mdx-js/mdx'
import {Fragment, useEffect, useState} from 'react'
import * as runtime from 'react/jsx-runtime'

/**
 * @param {{code: string}} props
 * @returns {JSX.Element}
 */
export default function Page({code}) {
  /** @type {[MDXModule | undefined, Dispatch<SetStateAction<MDXModule | undefined>>]} */
  const [mdxModule, setMdxModule] = useState()
  const Content = mdxModule ? mdxModule.default : Fragment

  useEffect(
    function () {
      ;(async function () {
        setMdxModule(await run(code, {...runtime, baseUrl: import.meta.url}))
      })()
    },
    [code]
  )

  return <Content />
}

export async function getStaticProps() {
  const code = String(
    await compile('# hi', {
      outputFormat: 'function-body'
      /* …otherOptions */
    })
  )
  return {props: {code}}
}