@amamo/mdx
本页目录

快速开始

本指南从一个 content/posts/hello.mdx 文件开始，最终得到宿主可 import 的模块、集合注册表 和配套声明文件。

要求

  • Node.js 20.19 或更新版本。 这是包声明的最低引擎版本。
  • 受支持的原生目标。 绑定没有 JavaScript 或 WASI 回退，详见原生目标。
  • 宿主应用使用 React 19。 默认 jsxImportSource 是 react。
  • MDX 作者可信。 编译后的 MDX 可以在宿主应用中执行 JavaScript。

安装

Shell
pnpm add @amamo/mdx

发布的根包会在安装时选择匹配的平台包。不要在不同操作系统、CPU 架构或 Linux libc 之间 复制 node_modules。

添加文档

创建集合目录和第一篇文档：

MDX
---
title: 你好
---

# 你好

这篇文档由 @amamo/mdx 编译。

将它保存为 content/posts/hello.mdx。

定义集合

集合 schema 使用包内与 Zod 兼容的 z.object；其它配置值必须是可序列化的纯数据。 defineConfig 是向支持 TypeScript 的工具暴露配置类型的恒等辅助函数；创建编译器或适配器时 才会转换 schema、执行校验并应用默认值。

JavaScript
// amamo.config.mjs
import { defineConfig, z } from '@amamo/mdx'

export default defineConfig({
  root: import.meta.dirname,
  collections: {
    posts: {
      directory: 'content/posts',
      schema: z.object({ title: z.string() }),
    },
  },
  manifests: {
    public: {
      output: '.amamo-mdx/public.json',
      fields: {
        key: 'key',
        slug: 'slug',
        title: 'title',
      },
    },
  },
})

完整构建开始前，content/posts 目录必须存在。集合、缓存、生成目录和 manifest 的相对路径 都从 root 解析。

选择由谁管理构建

Vite

TypeScript
// vite.config.ts
import { amamoMdx } from '@amamo/mdx/vite'
import { defineConfig } from 'vite'

import amamo from './amamo.config.mjs'

export default defineConfig({ plugins: [amamoMdx(amamo)] })

Vite 会执行一次完整的启动构建，直接转换被 import 的内容，并通过自己的 watcher 处理新增、 修改和删除事件。

Next

TypeScript
// next.config.ts
import { withAmamoMdx } from '@amamo/mdx/next'

import amamo from './amamo.config.mjs'

export default withAmamoMdx(amamo)({ reactStrictMode: true })

Next 会在开发或生产打包前构建持久化缓存，再为 Turbopack 和 Webpack 注册只读 loader。使用 这个适配器时必须保持缓存启用。

直接 API

JavaScript
// build-content.mjs
import { createCompiler } from '@amamo/mdx'

import amamo from './amamo.config.mjs'

const compiler = await createCompiler(amamo)
try {
  const result = await compiler.build()
  console.log(result)
} finally {
  await compiler.dispose()
}

运行这个脚本：

Shell
node build-content.mjs

如果生成产物必须表示整个集合，请在 transform() 或 remove() 前先调用 build()。增量方法 只更新编译器当前的内存记录集，不会自行发现未出现的同级文档。

导入内容

在已配置的 Vite 或 Next 应用中，可以像模块一样导入 MDX：

TSX
import Post, { frontmatter } from './content/posts/hello.mdx'

export function Page() {
  return (
    <main>
      <h1>{frontmatter.title}</h1>
      <Post />
    </main>
  )
}

也可以在应用代码中导入生成的集合注册表：

TypeScript
import { collections } from './.amamo-mdx/collections.mjs'

const hello = collections.posts.find((document) => document.slug === 'hello')
const module = await hello?.load()

load() 会 import 原始 MDX 路径，因此它必须运行在已经配置 Vite 插件或 Next loader 的宿主中。

生成文件

使用上面的配置，第一次构建会写出：

text
.amamo-mdx/
  cache/
  collections.d.ts
  collections.mjs
  index.json
  public.json
  • collections.mjs 包含排序后的元数据和延迟 import。
  • collections.d.ts 是集合注册表的配套声明文件。
  • index.json 把源码路径映射到 Next loader 使用的缓存记录；Vite 不读取它。
  • cache/ 保存可复用的编译记录，其中已经包含高亮结果。
  • public.json 是配置的 manifest；不同的 output 可以把 manifest 放到其它位置。

把 .amamo-mdx/ 加入宿主仓库的忽略文件。字节未变化的共享文件和 manifest 不会被重写。

接下来阅读配置参考，了解全部可用选项及其默认值。

Copyright © 2026 白熱.