0
# Parcel Transformer MDX
1
2
Parcel transformer plugin for MDX files that compiles MDX to React components. This transformer enables seamless processing of MDX (Markdown with JSX) files in Parcel applications by compiling them to JavaScript modules that can be imported and used as React components.
3
4
**Note**: This is a Parcel plugin, not a standalone library. It integrates with Parcel's build system to transform `.mdx` files during bundling.
5
6
## Package Information
7
8
- **Package Name**: @parcel/transformer-mdx
9
- **Package Type**: npm
10
- **Language**: JavaScript/Flow
11
- **Installation**: `npm install @parcel/transformer-mdx`
12
13
## Core Imports
14
15
This is a Parcel transformer plugin that is automatically registered when installed. It requires no direct imports in application code.
16
17
The transformer is included in Parcel's default configuration for `.mdx` files. For custom configurations, add to `.parcelrc`:
18
19
```json
20
{
21
"extends": "@parcel/config-default",
22
"transformers": {
23
"*.mdx": ["@parcel/transformer-mdx"]
24
}
25
}
26
```
27
28
## Basic Usage
29
30
Once the transformer is installed and configured, applications can import MDX files as React components. The transformer automatically processes `.mdx` files during the Parcel build process.
31
32
**Application usage after transformation:**
33
34
```typescript
35
// Import an MDX file as a React component
36
import MyDocument from './content/my-document.mdx';
37
38
// Use it in your React application
39
function App() {
40
return (
41
<div>
42
<h1>My App</h1>
43
<MyDocument />
44
</div>
45
);
46
}
47
```
48
49
**Example MDX file (`my-document.mdx`):**
50
51
```mdx
52
# Hello from MDX
53
54
This is a paragraph with **bold text**.
55
56
import Button from './Button';
57
58
<Button>Click me!</Button>
59
60
## Code Example
61
62
```javascript
63
console.log('Hello world');
64
```
65
```
66
67
## Architecture
68
69
The transformer integrates with Parcel's plugin system:
70
71
- **Plugin Type**: Transformer plugin using `new Transformer()` constructor
72
- **Framework**: Built on `@parcel/plugin` framework
73
- **Processing**: Uses `@mdx-js/mdx` to compile MDX to JavaScript with React imports
74
- **Output**: JavaScript modules with classic JSX runtime configuration
75
76
## Capabilities
77
78
### MDX Transformation
79
80
Transforms MDX files into JavaScript modules containing React components.
81
82
```javascript { .api }
83
/**
84
* Parcel Transformer instance for MDX files
85
* Automatically processes .mdx files when registered with Parcel
86
*/
87
export default Transformer;
88
89
/**
90
* Transformer implementation that processes MDX files
91
* Takes an asset parameter with destructured syntax
92
*/
93
interface TransformerImplementation {
94
transform({asset}: {asset: Asset}): Promise<Array<Asset>>;
95
}
96
97
/**
98
* Asset object representing the file being processed by Parcel
99
*/
100
interface Asset {
101
/** Get the source code content of the asset */
102
getCode(): Promise<string>;
103
/** Set the transformed code content */
104
setCode(code: string): void;
105
/** The asset type - changed from 'mdx' to 'js' after transformation */
106
type: string;
107
}
108
```
109
110
**Transformation Process:**
111
112
1. **Input**: `.mdx` files containing Markdown with JSX
113
2. **Compilation**: Uses `@mdx-js/mdx` to compile MDX to JavaScript
114
3. **Wrapping**: Adds React and MDX runtime imports:
115
- JSX runtime configuration (`/* @jsxRuntime classic */`)
116
- JSX pragma (`/* @jsx mdx */`)
117
- React import (`import React from 'react'`)
118
- MDX runtime import (`import { mdx } from '@mdx-js/react'`)
119
4. **Output**: JavaScript module ready for bundling
120
121
**Generated Output Format:**
122
123
```javascript { .api }
124
/* @jsxRuntime classic */
125
/* @jsx mdx */
126
import React from 'react';
127
import { mdx } from '@mdx-js/react'
128
// [compiled MDX content as JSX]
129
```
130
131
## Dependencies
132
133
### Runtime Dependencies
134
135
```javascript { .api }
136
/**
137
* Core dependencies required by the transformer
138
*/
139
interface Dependencies {
140
/** MDX compiler - converts MDX to JavaScript */
141
"@mdx-js/mdx": "^1.6.22";
142
/** Parcel plugin base class */
143
"@parcel/plugin": "2.13.3";
144
}
145
146
/**
147
* Peer dependencies required at runtime
148
*/
149
interface PeerDependencies {
150
/** MDX React runtime for component rendering */
151
"@mdx-js/react": "^1.6.22";
152
}
153
```
154
155
### Engine Requirements
156
157
- **Node.js**: >= 16.0.0
158
- **Parcel**: ^2.13.3
159
160
## Configuration
161
162
### Default Behavior
163
164
The transformer uses default MDX compilation settings with no custom configuration options. It automatically:
165
166
- Processes all `.mdx` files
167
- Compiles using `@mdx-js/mdx` v1.6.22
168
- Generates classic JSX runtime output
169
- Requires `@mdx-js/react` for runtime support
170
171
### File Extensions
172
173
Automatically handles files with the `.mdx` extension when registered with Parcel.
174
175
## Error Handling
176
177
The transformer may throw errors during compilation if:
178
179
- The MDX file contains invalid syntax
180
- Required dependencies are missing
181
- The compilation process fails
182
183
Errors are handled by Parcel's error reporting system and will prevent the build from completing successfully.
184
185
## Integration
186
187
### Parcel Plugin Registration
188
189
The transformer is included in Parcel's default configuration at line 36 of `@parcel/config-default`. It automatically processes `.mdx` files without additional configuration.
190
191
For custom configurations, add to `.parcelrc`:
192
193
```json
194
{
195
"extends": "@parcel/config-default",
196
"transformers": {
197
"*.mdx": ["@parcel/transformer-mdx"]
198
}
199
}
200
```
201
202
### Development Workflow
203
204
1. Install the transformer: `npm install @parcel/transformer-mdx`
205
2. Install the peer dependency: `npm install @mdx-js/react`
206
3. Create `.mdx` files in your project
207
4. Import and use them as React components
208
5. Run Parcel build - MDX files are automatically transformed