or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-mdx-js--loader

Webpack loader for processing MDX files into React components

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@mdx-js/loader@3.1.x

To install, run

npx @tessl/cli install tessl/npm-mdx-js--loader@3.1.0

index.mddocs/

MDX Loader

MDX Loader is a webpack loader for processing MDX files. It compiles MDX (Markdown with JSX) files into React components that can be bundled by webpack, enabling seamless integration of MDX content into webpack-based build systems. The loader compiles MDX files into React components, supporting all features of the MDX compiler including JSX expressions, component imports, and custom syntax extensions.

Package Information

  • Package Name: @mdx-js/loader
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @mdx-js/loader

Core Imports

The package exports a single webpack loader as the default export:

// Webpack configuration usage - no direct imports needed
module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: ['@mdx-js/loader']
      }
    ]
  }
};

Basic Usage

Basic Webpack Configuration

/**
 * @import {Configuration} from 'webpack'
 */

/** @type {Configuration} */
const webpackConfig = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: '@mdx-js/loader',
            options: {
              // MDX compiler options
            }
          }
        ]
      }
    ]
  }
};

export default webpackConfig;

With Options

/** @type {Configuration} */
const webpackConfig = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: '@mdx-js/loader',
            options: {
              jsxImportSource: 'preact',
              remarkPlugins: [remarkGfm],
              rehypePlugins: [rehypeHighlight]
            }
          }
        ]
      }
    ]
  }
};

Combined with Babel

/** @type {Configuration} */
const webpackConfig = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          // Note: Webpack runs right-to-left
          {loader: 'babel-loader', options: {}},
          {
            loader: '@mdx-js/loader',
            options: {}
          }
        ]
      }
    ]
  }
};

Architecture

The loader is designed as a bridge between MDX content and webpack bundling:

  • CommonJS Wrapper: The main export (index.cjs) is a CommonJS module required by webpack
  • ESM Implementation: The core loader logic is implemented in ESM (lib/index.js) and dynamically imported
  • Caching System: Per-compiler instance caching based on options hash for performance
  • MDX Integration: Uses @mdx-js/mdx compiler internally via createFormatAwareProcessors
  • Source Map Support: Automatic source map generation when webpack is configured for it
  • Development Mode: Automatic detection of webpack's development/production mode

Capabilities

Webpack Loader Function

The main loader function that processes MDX files within webpack's module system.

/**
 * Webpack loader for MDX files (CommonJS wrapper)
 * @this {LoaderContext<unknown>} Webpack loader context
 * @param {string} code - MDX source code
 * @returns {undefined} Uses async callback pattern via this.async()
 */
function loader(code);

/**
 * Core ESM loader implementation
 * @this {LoaderContext<unknown>} Webpack loader context
 * @param {string} value - MDX source code
 * @param {LoaderContext<unknown>['callback']} callback - Webpack async callback
 * @returns {undefined} Calls callback with results
 */
function loader(value, callback);

The loader uses webpack's async callback pattern and processes MDX content through the following steps:

  1. Retrieves loader options via this.getOptions()
  2. Creates a hash of options for caching
  3. Configures source map and development mode based on webpack settings
  4. Retrieves or creates a cached processor instance
  5. Processes the MDX content and returns compiled JavaScript

Configuration Options

Configuration options that can be passed to the loader via webpack configuration.

/**
 * Configuration options for @mdx-js/loader
 * Same as CompileOptions from @mdx-js/mdx except for SourceMapGenerator and development
 */
type Options = Omit<CompileOptions, 'SourceMapGenerator' | 'development'>;

interface CompileOptions {
  /** File format detection ('detect' is default) */
  format?: 'detect' | 'md' | 'mdx' | null | undefined;
  /** Whether to keep JSX instead of compiling it away (default: false) */
  jsx?: boolean | null | undefined;
  /** Where to import automatic JSX runtimes from (default: 'react') */
  jsxImportSource?: string | null | undefined;
  /** JSX runtime to use (default: 'automatic') */
  jsxRuntime?: 'automatic' | 'classic' | null | undefined;
  /** Output format (default: 'program') */
  outputFormat?: 'function-body' | 'program' | null | undefined;
  /** Base URL for import resolution (example: import.meta.url) */
  baseUrl?: URL | string | null | undefined;
  /** Casing for attribute names (default: 'react') */
  elementAttributeNameCase?: 'react' | 'html' | null | undefined;
  /** Casing for CSS property names (default: 'dom') */
  stylePropertyNameCase?: 'dom' | 'css' | null | undefined;
  /** Convert table cell align attributes to CSS styles (default: true) */
  tableCellAlignToStyle?: boolean | null | undefined;
  /** Markdown file extensions */
  mdExtensions?: ReadonlyArray<string> | null | undefined;
  /** MDX file extensions */
  mdxExtensions?: ReadonlyArray<string> | null | undefined;
  /** List of remark (markdown) plugins */
  remarkPlugins?: PluggableList | null | undefined;
  /** List of rehype (HTML) plugins */
  rehypePlugins?: PluggableList | null | undefined;
  /** List of recma (JavaScript) plugins */
  recmaPlugins?: PluggableList | null | undefined;
  /** Options for remark-rehype plugin */
  remarkRehypeOptions?: Readonly<RemarkRehypeOptions> | null | undefined;
  /** Where to import MDX provider from (example: '@mdx-js/react') */
  providerImportSource?: string | null | undefined;
  /** @deprecated JSX pragma for classic runtime (default: 'React.createElement') */
  pragma?: string | null | undefined;
  /** @deprecated JSX fragment for classic runtime (default: 'React.Fragment') */
  pragmaFrag?: string | null | undefined;
  /** @deprecated JSX import source for classic runtime (default: 'react') */
  pragmaImportSource?: string | null | undefined;
}

interface PluggableList extends Array<Pluggable> {}
interface Pluggable extends Array<any> {
  0: Plugin;
  1?: Options;
}
interface Plugin extends Function {}

Key Configuration Notes:

  • SourceMapGenerator and development options are automatically handled by the loader based on webpack configuration
  • development is set based on webpack's mode (development vs production)
  • SourceMapGenerator is set when webpack source maps are enabled
  • All other options from @mdx-js/mdx CompileOptions are supported

Caching Mechanism

The loader implements a sophisticated caching system for performance optimization.

/**
 * Cache structure for storing compiled processors
 * WeakMap keyed by webpack compiler instance, containing Maps of option hashes to processors
 */
const cache = new WeakMap<WebpackCompiler, Map<string, Process>>();

/**
 * Generate hash for options to enable caching
 * @param {Readonly<Options>} options - Loader configuration options
 * @returns {string} Hash string for cache key
 */
function getOptionsHash(options);

The caching system:

  1. Uses WeakMap keyed by webpack compiler instance to ensure proper cleanup
  2. Within each compiler cache, uses option hash as key for processor instances
  3. Prevents recompilation when same options are used across multiple files
  4. Automatically handles cache invalidation when options change

Types

The loader integrates with webpack's type system and MDX compiler types:

/**
 * Webpack loader context interface
 */
interface LoaderContext<T> {
  /** Get loader options with type safety */
  getOptions(): T;
  /** Webpack compiler instance */
  _compiler?: WebpackCompiler;
  /** Current file path being processed */
  resourcePath: string;
  /** Directory context for relative paths */
  context: string;
  /** Whether source maps are enabled */
  sourceMap: boolean;
  /** Webpack build mode */
  mode: 'development' | 'production';
  /** Async callback for returning results */
  callback: (error: Error | null, content?: Buffer, sourceMap?: any) => void;
  /** Get async callback function */
  async(): LoaderContext['callback'];
}

/**
 * MDX processor function type
 */
interface Process {
  (vfileCompatible: Compatible): Promise<VFile>;
}

/**
 * VFile-compatible input types
 */
type Compatible = VFile | Buffer | Uint8Array | string;

Error Handling

The loader provides enhanced error messages with file path context:

  • File paths are made relative to webpack context for cleaner error output
  • MDX compilation errors include file location information
  • Webpack's error handling system is used for proper error reporting
  • Deprecated options (like renderer) are detected and result in helpful error messages

Compatibility

  • Webpack: Requires webpack 5 or higher
  • Node.js: Requires Node.js 16 or higher
  • Module System: ESM-only package with CommonJS wrapper for webpack compatibility
  • TypeScript: Fully typed with JSDoc annotations for type safety
  • React: Works with React 16.14+, React 17, and React 18
  • Other JSX: Supports Preact, Vue, and other JSX frameworks via jsxImportSource option