Parcel Transformer MDX

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.

Note: This is a Parcel plugin, not a standalone library. It integrates with Parcel's build system to transform .mdx files during bundling.

Package Information

• Package Name: @parcel/transformer-mdx
• Package Type: npm
• Language: JavaScript/Flow
• Installation: npm install @parcel/transformer-mdx

Core Imports

This is a Parcel transformer plugin that is automatically registered when installed. It requires no direct imports in application code.

The transformer is included in Parcel's default configuration for .mdx files. For custom configurations, add to .parcelrc:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.mdx": ["@parcel/transformer-mdx"]
  }
}

Basic Usage

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.

Application usage after transformation:

// Import an MDX file as a React component
import MyDocument from './content/my-document.mdx';

// Use it in your React application
function App() {
  return (
    <div>
      <h1>My App</h1>
      <MyDocument />
    </div>
  );
}

Example MDX file (my-document.mdx):

# Hello from MDX

This is a paragraph with **bold text**.

import Button from './Button';

<Button>Click me!</Button>

## Code Example

```javascript
console.log('Hello world');

## Architecture

The transformer integrates with Parcel's plugin system:

- **Plugin Type**: Transformer plugin using `new Transformer()` constructor
- **Framework**: Built on `@parcel/plugin` framework
- **Processing**: Uses `@mdx-js/mdx` to compile MDX to JavaScript with React imports
- **Output**: JavaScript modules with classic JSX runtime configuration

## Capabilities

### MDX Transformation

Transforms MDX files into JavaScript modules containing React components.

```javascript { .api }
/**
 * Parcel Transformer instance for MDX files
 * Automatically processes .mdx files when registered with Parcel
 */
export default Transformer;

/**
 * Transformer implementation that processes MDX files
 * Takes an asset parameter with destructured syntax
 */
interface TransformerImplementation {
  transform({asset}: {asset: Asset}): Promise<Array<Asset>>;
}

/**
 * Asset object representing the file being processed by Parcel
 */
interface Asset {
  /** Get the source code content of the asset */
  getCode(): Promise<string>;
  /** Set the transformed code content */
  setCode(code: string): void;
  /** The asset type - changed from 'mdx' to 'js' after transformation */
  type: string;
}

Transformation Process:

1. Input: .mdx files containing Markdown with JSX
2. Compilation: Uses @mdx-js/mdx to compile MDX to JavaScript
3. Wrapping: Adds React and MDX runtime imports:
   • JSX runtime configuration (/* @jsxRuntime classic */)
   • JSX pragma (/* @jsx mdx */)
   • React import (import React from 'react')
   • MDX runtime import (import { mdx } from '@mdx-js/react')
4. Output: JavaScript module ready for bundling

Generated Output Format:

/* @jsxRuntime classic */
/* @jsx mdx */
import React from 'react';
import { mdx } from '@mdx-js/react'
// [compiled MDX content as JSX]

Dependencies

Runtime Dependencies

/**
 * Core dependencies required by the transformer
 */
interface Dependencies {
  /** MDX compiler - converts MDX to JavaScript */
  "@mdx-js/mdx": "^1.6.22";
  /** Parcel plugin base class */
  "@parcel/plugin": "2.13.3";
}

/**
 * Peer dependencies required at runtime
 */
interface PeerDependencies {
  /** MDX React runtime for component rendering */
  "@mdx-js/react": "^1.6.22";
}

Engine Requirements

• Node.js: >= 16.0.0
• Parcel: ^2.13.3

Configuration

Default Behavior

The transformer uses default MDX compilation settings with no custom configuration options. It automatically:

• Processes all .mdx files
• Compiles using @mdx-js/mdx v1.6.22
• Generates classic JSX runtime output
• Requires @mdx-js/react for runtime support

File Extensions

Automatically handles files with the .mdx extension when registered with Parcel.

Error Handling

The transformer may throw errors during compilation if:

• The MDX file contains invalid syntax
• Required dependencies are missing
• The compilation process fails

Errors are handled by Parcel's error reporting system and will prevent the build from completing successfully.

Integration

Parcel Plugin Registration

The transformer is included in Parcel's default configuration at line 36 of @parcel/config-default. It automatically processes .mdx files without additional configuration.

For custom configurations, add to .parcelrc:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.mdx": ["@parcel/transformer-mdx"]
  }
}

Development Workflow

1. Install the transformer: npm install @parcel/transformer-mdx
2. Install the peer dependency: npm install @mdx-js/react
3. Create .mdx files in your project
4. Import and use them as React components
5. Run Parcel build - MDX files are automatically transformed