---
description: Compile trusted MDX into JavaScript modules for a configurable JSX runtime, collection metadata, and deterministic JSON manifests.
---

# A native MDX content compiler

Give `@amamo/mdx` a directory of MDX files and a Zod object schema. A build converts the schema to
JSON Schema, validates the frontmatter, compiles each document for the configured JSX runtime (React
by default), highlights fenced code with Shiki, and writes a collection registry, companion
declaration, and configured manifests.

<InstallTabs packageName="@amamo/mdx" />

## Choose a path

| I want to...                    | Start here                       |
| ------------------------------- | -------------------------------- |
| Compile content in a Vite app   | [Vite 8](/vite/)                 |
| Import MDX in a Next app        | [Next 16](/next/)                |
| Drive builds from my own script | [Compiler API](/compiler-api/)   |
| See every config default        | [Configuration](/configuration/) |

## One document through the pipeline

```text
MDX source + config
  -> TypeScript: Zod to JSON Schema, discovery, operation queue
  -> Rust: YAML, JSON Schema, MDX tree, media, derived fields
  -> JavaScript: official Shiki themes, grammars, and engine
  -> Rust: highlighted module, validated metadata, manifest projections, cache record
  -> TypeScript: collections.mjs, collections.d.ts, index.json, manifests
```

Rust owns parsing, validation, MDX compilation, manifest projection, and persistent records. Shiki
stays in JavaScript; its highlighted HAST is validated and injected before Rust emits the final
module. The direct API, Vite plugin, and Next wrapper share this implementation, but each compiler
or adapter instance owns its own state.

## What a build gives you

- A JavaScript module for every imported MDX document, including `frontmatter` and enabled derived
  exports.
- `collections.mjs`, a deterministic registry of document metadata and lazy source imports.
- `collections.d.ts`, a companion declaration output for the registry.
- Optional JSON manifests with explicit field projection, sorting, and array or keyed-object output.
- BLAKE3-addressed cache records so unchanged documents can skip native compilation and Shiki.

Relative media URLs written in Markdown become static imports after fresh-compilation root checks.
Authored MDX JSX is compiled as part of MDX, but media attributes inside it are not rewritten.

## Deliberate boundaries

- **Trusted content only.** MDX can execute JavaScript when its compiled module is imported or
  rendered. Schema validation is not a sandbox.
- **Build-time compiler, not a runtime.** The host imports or renders emitted modules with the
  configured JSX runtime.
- **Plain-data configuration.** Functions, class instances, symbols, accessors, cycles, and
  non-finite numbers are rejected after the config value is loaded.
- **Native targets only.** There is no JavaScript or WASI fallback. See [Native targets](/native-targets/).

Continue with [Getting started](/getting-started/) for a complete first document.