0
# @mdx-js/mdx
1

2
@mdx-js/mdx is the core compiler that transforms MDX documents into JavaScript. MDX is an authorable format that seamlessly blends markdown with JSX, enabling the creation of interactive content by importing and embedding React components directly within markdown documents.
3

4
## Package Information
5

6
- **Package Name**: @mdx-js/mdx
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @mdx-js/mdx`
10

11
## Core Imports
12

13
```typescript
14
import { compile, compileSync, createProcessor, evaluate, evaluateSync, run, runSync, nodeTypes } from "@mdx-js/mdx";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { compile, compileSync, createProcessor, evaluate, evaluateSync, run, runSync, nodeTypes } = require("@mdx-js/mdx");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { compile } from "@mdx-js/mdx";
27

28
// Basic compilation
29
const mdxSource = `# Hello World
30

31
<MyComponent prop="value" />
32

33
export const metadata = { title: "Example" };`;
34

35
const compiled = await compile(mdxSource, {
36
  jsx: false,
37
  format: 'mdx'
38
});
39

40
console.log(String(compiled));
41
```
42

43
## Architecture
44

45
@mdx-js/mdx processes MDX through a unified pipeline:
46

47
- **MDX Parsing**: Parses markdown with JSX extensions using remark-mdx
48
- **AST Transformation**: Converts MDX AST through mdast → hast → esast transformations
49
- **Code Generation**: Generates JavaScript code that renders to JSX runtime calls
50
- **Plugin System**: Supports remark, rehype, and recma plugins for customization
51
- **Runtime Integration**: Works with React, Preact, Vue and other JSX runtimes
52

53
## Capabilities
54

55
### Compilation
56

57
Core compilation functionality that transforms MDX source code into executable JavaScript. Supports both sync and async compilation with extensive configuration options.
58

59
```typescript { .api }
60
function compile(
61
  vfileCompatible: Compatible,
62
  compileOptions?: CompileOptions
63
): Promise<VFile>;
64

65
function compileSync(
66
  vfileCompatible: Compatible, 
67
  compileOptions?: CompileOptions
68
): VFile;
69
```
70

71
[Compilation](./compilation.md)
72

73
### Processor Creation
74

75
Advanced processor creation for building custom MDX transformation pipelines with full control over the unified processor chain.
76

77
```typescript { .api }
78
function createProcessor(options?: ProcessorOptions): Processor<Root, Program, Program, Program, string>;
79

80
interface ProcessorOptions {
81
  format?: 'md' | 'mdx';
82
  jsx?: boolean;
83
  jsxRuntime?: 'automatic' | 'classic';
84
  jsxImportSource?: string;
85
  development?: boolean;
86
  outputFormat?: 'program' | 'function-body';
87
  baseUrl?: URL | string;
88
  remarkPlugins?: PluggableList;
89
  rehypePlugins?: PluggableList;  
90
  recmaPlugins?: PluggableList;
91
}
92
```
93

94
[Processor Creation](./processor.md)
95

96
### Evaluation and Runtime
97

98
Safe evaluation and runtime execution of compiled MDX code. These functions compile and immediately execute MDX, ideal for development and dynamic content scenarios.
99

100
```typescript { .api }
101
function evaluate(
102
  file: Compatible,
103
  options: EvaluateOptions
104
): Promise<MDXModule>;
105

106
function run(
107
  code: {toString(): string},
108
  options: RunOptions
109
): Promise<MDXModule>;
110

111
interface EvaluateOptions {
112
  Fragment: Fragment;
113
  jsx?: Jsx;
114
  jsxDEV?: JsxDev; 
115
  jsxs?: Jsx;
116
  baseUrl?: URL | string;
117
  useMDXComponents?: UseMdxComponents;
118
}
119
```
120

121
[Evaluation and Runtime](./evaluation.md)
122

123
## Core Types
124

125
```typescript { .api }
126
interface VFile {
127
  value: string;
128
  map?: SourceMapGenerator;
129
  toString(): string;
130
}
131

132
interface MDXModule {
133
  default: ComponentType<any>;
134
  [key: string]: any;
135
}
136

137
type Compatible = VFile | VFileValue | URL | string;
138
type VFileValue = string | Uint8Array;
139

140
type Fragment = ComponentType<{children?: ReactNode}>;
141
type Jsx = (type: any, props: any, key?: any) => any;
142
type JsxDev = (type: any, props: any, key?: any, isStaticChildren?: boolean, source?: any, self?: any) => any;
143

144
interface UseMdxComponents {
145
  (): MDXComponents;
146
}
147

148
interface MDXComponents {
149
  [key: string]: ComponentType<any>;
150
}
151
```
152

153
## Constants
154

155
```typescript { .api }
156
const nodeTypes: readonly ['mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression', 'mdxjsEsm'];
157
```
158

159
MDX node types that are passed through untouched from the mdast tree to the hast tree during processing.