0
# Compilation
1

2
Core compilation functionality that transforms MDX source code into executable JavaScript. The compilation process converts MDX documents through a unified processing pipeline, supporting both synchronous and asynchronous operations with extensive configuration options.
3

4
## Capabilities
5

6
### Compile Function
7

8
Asynchronously compiles MDX source code to JavaScript.
9

10
```typescript { .api }
11
/**
12
 * Compile MDX to JavaScript
13
 * @param vfileCompatible - MDX document to parse (string, Buffer, VFile, or URL)
14
 * @param compileOptions - Optional compilation configuration
15
 * @returns Promise resolving to compiled VFile with JavaScript code
16
 */
17
function compile(
18
  vfileCompatible: Compatible,
19
  compileOptions?: CompileOptions
20
): Promise<VFile>;
21
```
22

23
**Usage Examples:**
24

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

28
// Basic compilation
29
const result = await compile('# Hello\n\n<Button>Click me</Button>');
30
console.log(String(result));
31

32
// With options
33
const result = await compile(
34
  '# Hello World',
35
  {
36
    format: 'mdx',
37
    jsx: true,
38
    development: true
39
  }
40
);
41
```
42

43
### CompileSync Function
44

45
Synchronously compiles MDX source code to JavaScript. Use the async `compile` when possible for better performance.
46

47
```typescript { .api }
48
/**
49
 * Synchronously compile MDX to JavaScript
50
 * @param vfileCompatible - MDX document to parse
51
 * @param compileOptions - Optional compilation configuration
52
 * @returns Compiled VFile with JavaScript code
53
 */
54
function compileSync(
55
  vfileCompatible: Compatible,
56
  compileOptions?: CompileOptions
57
): VFile;
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import { compileSync } from "@mdx-js/mdx";
64

65
// Synchronous compilation
66
const result = compileSync('# Hello\n\n<Button>Click me</Button>');
67
console.log(String(result));
68

69
// File input
70
import { readFileSync } from 'fs';
71
const mdxContent = readFileSync('example.mdx', 'utf8');
72
const result = compileSync(mdxContent, { format: 'mdx' });
73
```
74

75
## Configuration
76

77
### CompileOptions Interface
78

79
Configuration options for compilation functions.
80

81
```typescript { .api }
82
interface CompileOptions {
83
  /** Format of the input file - 'detect' automatically detects based on extension */
84
  format?: 'detect' | 'md' | 'mdx';
85
  
86
  /** Whether to keep JSX instead of compiling it away */
87
  jsx?: boolean;
88
  
89
  /** JSX runtime to use */
90
  jsxRuntime?: 'automatic' | 'classic';
91
  
92
  /** Where to import automatic JSX runtime from */
93
  jsxImportSource?: string;
94
  
95
  /** Whether to add development info for better error messages */
96
  development?: boolean;
97
  
98
  /** Output format for generated code */
99
  outputFormat?: 'program' | 'function-body';
100
  
101
  /** Base URL for resolving imports */
102
  baseUrl?: URL | string;
103
  
104
  /** Source map generator class */
105
  SourceMapGenerator?: typeof SourceMapGenerator;
106
  
107
  /** Attribute name casing for HTML elements */
108
  elementAttributeNameCase?: 'react' | 'html';
109
  
110
  /** Style property name casing */
111
  stylePropertyNameCase?: 'dom' | 'css';
112
  
113
  /** Convert align attributes to CSS styles */
114
  tableCellAlignToStyle?: boolean;
115
  
116
  /** Markdown file extensions */
117
  mdExtensions?: ReadonlyArray<string>;
118
  
119
  /** MDX file extensions */
120
  mdxExtensions?: ReadonlyArray<string>;
121
  
122
  /** Provider import source for components */
123
  providerImportSource?: string;
124
  
125
  /** Remark plugins for markdown processing */
126
  remarkPlugins?: PluggableList;
127
  
128
  /** Rehype plugins for HTML processing */
129
  rehypePlugins?: PluggableList;
130
  
131
  /** Recma plugins for JavaScript generation */
132
  recmaPlugins?: PluggableList;
133
  
134
  /** Options for remark-rehype transformation */
135
  remarkRehypeOptions?: RemarkRehypeOptions;
136
}
137
```
138

139
**Configuration Examples:**
140

141
```typescript
142
// React with TypeScript
143
const reactOptions: CompileOptions = {
144
  format: 'mdx',
145
  jsx: false,
146
  jsxRuntime: 'automatic',
147
  jsxImportSource: 'react',
148
  development: false
149
};
150

151
// Preact integration
152
const preactOptions: CompileOptions = {
153
  jsx: false,
154
  jsxRuntime: 'automatic', 
155
  jsxImportSource: 'preact',
156
  providerImportSource: '@mdx-js/preact'
157
};
158

159
// Development mode with source maps
160
const devOptions: CompileOptions = {
161
  development: true,
162
  SourceMapGenerator: require('source-map').SourceMapGenerator,
163
  jsx: false
164
};
165

166
// Custom plugins
167
const customOptions: CompileOptions = {
168
  remarkPlugins: [
169
    'remark-gfm',
170
    ['remark-toc', { heading: 'contents' }]
171
  ],
172
  rehypePlugins: [
173
    'rehype-slug',
174
    'rehype-autolink-headings'
175
  ]
176
};
177
```
178

179
## Input Types
180

181
### Compatible Type
182

183
Union type representing all valid input formats for compilation functions.
184

185
```typescript { .api }
186
type Compatible = VFile | VFileValue | URL | string;
187
type VFileValue = string | Uint8Array;
188
```
189

190
### VFile Interface
191

192
Virtual file object used for input and output.
193

194
```typescript { .api }
195
interface VFile {
196
  /** File contents as string */
197
  value: string;
198
  
199
  /** Optional source map */
200
  map?: SourceMapGenerator;
201
  
202
  /** File path */
203
  path?: string;
204
  
205
  /** File basename */
206
  basename?: string;
207
  
208
  /** File directory */
209
  dirname?: string;
210
  
211
  /** File extension */
212
  extname?: string;
213
  
214
  /** Convert to string */
215
  toString(): string;
216
}
217
```
218

219
## Error Handling
220

221
Compilation functions throw errors for:
222

223
- **Syntax errors** in MDX source code
224
- **Invalid JSX** that cannot be parsed
225
- **Plugin errors** during processing
226
- **File system errors** when reading files
227
- **Configuration errors** for invalid options
228

229
```typescript
230
try {
231
  const result = await compile(mdxSource);
232
} catch (error) {
233
  if (error.name === 'VFileMessage') {
234
    console.error('MDX Error:', error.message);
235
    console.error('Location:', error.location);
236
  }
237
  throw error;
238
}
239
```