按需 MDX

1-2 分钟阅读
作者：Titus Wormer

按需 MDX

本指南展示了如何使用 @mdx-js/mdx 在服务器上编译 MDX 并在客户端运行结果。一些框架，如 Next.js 和 Remix，使得在服务器和客户端之间分割工作变得容易。使用它，例如可以按需在服务器上完成大部分工作，而不是在构建时，然后将结果数据传递给客户端，客户端最终使用它。

这类似于人们有时使用 mdx-bundler 或 next-mdx-remote 的方式，但 MDX 也支持它。

快速示例

在服务器上：

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

const code: string

var String: StringConstructor
(value?: any) => string

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

(property) outputFormat?: "function-body" | "program" | null | undefined

在客户端：

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

import runtime

const code: ""

(property) MDXModule.default: MDXContent

const Content: MDXContent

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

const code: ""

import runtime

(property) baseUrl?: string | URL | null | undefined

(property) ImportMeta.url: string

The absolute file: URL of the module.

This is defined exactly the same as it is in browsers providing the URL of the current module file.

This enables useful patterns such as relative file loading:

import { readFileSync } from 'node:fs';
const buffer = readFileSync(new URL('./data.proto', import.meta.url));

Content 现在是一个 MDXContent 组件，你可以在你的框架中正常使用（参见§ 使用 MDX）。

更多信息可在 @mdx-js/mdx 的 API 文档中找到，关于 compile 和 run。对于其他用例，你也可以使用 evaluate，它在一个步骤中编译并运行。

注意：MDX 不是打包器（esbuild、webpack 和 Rollup 是打包器）：你不能从服务器上的 MDX 字符串中导入其他代码并获得精简的包。

Next.js 示例

一些框架让你在一个文件中编写服务器和客户端代码，例如 Next。

pages/hello.js

/**
 * @import {MDXModule} from 'mdx/types.js'
 * @import {Dispatch, ReactElement, 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 {ReactElement}
 */
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}}
}

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

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

(alias) const Fragment: ExoticComponent<FragmentProps>
import Fragment

Lets you group elements without a wrapper node.

@see {@link https://react.dev/reference/react/Fragment React Docs}

@example

import { Fragment } from 'react';

<Fragment>
  <td>Hello</td>
  <td>World</td>
</Fragment>

@example

// Using the <></> shorthand syntax:

<>
  <td>Hello</td>
  <td>World</td>
</>

(alias) function useEffect(effect: EffectCallback, deps?: DependencyList): void
import useEffect

(alias) function useState<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>] (+1 overload)
import useState

import runtime

function Page({ code }: {
    code: string;
}): ReactElement

(parameter) code: string

const mdxModule: MDXModule | undefined

const setMdxModule: Dispatch<SetStateAction<MDXModule | undefined>>

(alias) useState<MDXModule>(): [MDXModule | undefined, Dispatch<SetStateAction<MDXModule | undefined>>] (+1 overload)
import useState

const Content: ExoticComponent<FragmentProps> | MDXContent

const mdxModule: MDXModule | undefined

const mdxModule: MDXModule

(property) MDXModule.default: MDXContent

(alias) const Fragment: ExoticComponent<FragmentProps>
import Fragment

Lets you group elements without a wrapper node.

@see {@link https://react.dev/reference/react/Fragment React Docs}

@example

import { Fragment } from 'react';

<Fragment>
  <td>Hello</td>
  <td>World</td>
</Fragment>

@example

// Using the <></> shorthand syntax:

<>
  <td>Hello</td>
  <td>World</td>
</>

(alias) useEffect(effect: EffectCallback, deps?: DependencyList): void
import useEffect

const setMdxModule: (value: SetStateAction<MDXModule | undefined>) => void

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

(parameter) code: string

import runtime

(property) baseUrl?: string | URL | null | undefined

(property) ImportMeta.url: string

The absolute file: URL of the module.

This is defined exactly the same as it is in browsers providing the URL of the current module file.

This enables useful patterns such as relative file loading:

import { readFileSync } from 'node:fs';
const buffer = readFileSync(new URL('./data.proto', import.meta.url));

(parameter) code: string

const Content: ExoticComponent<FragmentProps> | MDXContent

function getStaticProps(): Promise<{
    props: {
        code: string;
    };
}>

const code: string

var String: StringConstructor
(value?: any) => string

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

(property) outputFormat?: "function-body" | "program" | null | undefined

(property) props: {
    code: string;
}

(property) code: string