tessl/npm-mdx-js--mdx

MDX compiler that transforms MDX documents into JavaScript

Overall
score

97%

Overview

Eval results

Files

Compilation

Name: tessl/npm-mdx-js--mdx
Author: tessl

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.

Capabilities

Compile Function

Asynchronously compiles MDX source code to JavaScript.

/**
 * Compile MDX to JavaScript
 * @param vfileCompatible - MDX document to parse (string, Buffer, VFile, or URL)
 * @param compileOptions - Optional compilation configuration
 * @returns Promise resolving to compiled VFile with JavaScript code
 */
function compile(
  vfileCompatible: Compatible,
  compileOptions?: CompileOptions
): Promise<VFile>;

Usage Examples:

import { compile } from "@mdx-js/mdx";

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

// With options
const result = await compile(
  '# Hello World',
  {
    format: 'mdx',
    jsx: true,
    development: true
  }
);

CompileSync Function

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

/**
 * Synchronously compile MDX to JavaScript
 * @param vfileCompatible - MDX document to parse
 * @param compileOptions - Optional compilation configuration
 * @returns Compiled VFile with JavaScript code
 */
function compileSync(
  vfileCompatible: Compatible,
  compileOptions?: CompileOptions
): VFile;

Usage Examples:

import { compileSync } from "@mdx-js/mdx";

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

// File input
import { readFileSync } from 'fs';
const mdxContent = readFileSync('example.mdx', 'utf8');
const result = compileSync(mdxContent, { format: 'mdx' });

Configuration

CompileOptions Interface

Configuration options for compilation functions.

interface CompileOptions {
  /** Format of the input file - 'detect' automatically detects based on extension */
  format?: 'detect' | 'md' | 'mdx';
  
  /** Whether to keep JSX instead of compiling it away */
  jsx?: boolean;
  
  /** JSX runtime to use */
  jsxRuntime?: 'automatic' | 'classic';
  
  /** Where to import automatic JSX runtime from */
  jsxImportSource?: string;
  
  /** Whether to add development info for better error messages */
  development?: boolean;
  
  /** Output format for generated code */
  outputFormat?: 'program' | 'function-body';
  
  /** Base URL for resolving imports */
  baseUrl?: URL | string;
  
  /** Source map generator class */
  SourceMapGenerator?: typeof SourceMapGenerator;
  
  /** Attribute name casing for HTML elements */
  elementAttributeNameCase?: 'react' | 'html';
  
  /** Style property name casing */
  stylePropertyNameCase?: 'dom' | 'css';
  
  /** Convert align attributes to CSS styles */
  tableCellAlignToStyle?: boolean;
  
  /** Markdown file extensions */
  mdExtensions?: ReadonlyArray<string>;
  
  /** MDX file extensions */
  mdxExtensions?: ReadonlyArray<string>;
  
  /** Provider import source for components */
  providerImportSource?: string;
  
  /** Remark plugins for markdown processing */
  remarkPlugins?: PluggableList;
  
  /** Rehype plugins for HTML processing */
  rehypePlugins?: PluggableList;
  
  /** Recma plugins for JavaScript generation */
  recmaPlugins?: PluggableList;
  
  /** Options for remark-rehype transformation */
  remarkRehypeOptions?: RemarkRehypeOptions;
}

Configuration Examples:

// React with TypeScript
const reactOptions: CompileOptions = {
  format: 'mdx',
  jsx: false,
  jsxRuntime: 'automatic',
  jsxImportSource: 'react',
  development: false
};

// Preact integration
const preactOptions: CompileOptions = {
  jsx: false,
  jsxRuntime: 'automatic', 
  jsxImportSource: 'preact',
  providerImportSource: '@mdx-js/preact'
};

// Development mode with source maps
const devOptions: CompileOptions = {
  development: true,
  SourceMapGenerator: require('source-map').SourceMapGenerator,
  jsx: false
};

// Custom plugins
const customOptions: CompileOptions = {
  remarkPlugins: [
    'remark-gfm',
    ['remark-toc', { heading: 'contents' }]
  ],
  rehypePlugins: [
    'rehype-slug',
    'rehype-autolink-headings'
  ]
};

Input Types

Compatible Type

Union type representing all valid input formats for compilation functions.

type Compatible = VFile | VFileValue | URL | string;
type VFileValue = string | Uint8Array;

VFile Interface

Virtual file object used for input and output.

interface VFile {
  /** File contents as string */
  value: string;
  
  /** Optional source map */
  map?: SourceMapGenerator;
  
  /** File path */
  path?: string;
  
  /** File basename */
  basename?: string;
  
  /** File directory */
  dirname?: string;
  
  /** File extension */
  extname?: string;
  
  /** Convert to string */
  toString(): string;
}

Error Handling

Compilation functions throw errors for:

Syntax errors in MDX source code
Invalid JSX that cannot be parsed
Plugin errors during processing
File system errors when reading files
Configuration errors for invalid options

try {
  const result = await compile(mdxSource);
} catch (error) {
  if (error.name === 'VFileMessage') {
    console.error('MDX Error:', error.message);
    console.error('Location:', error.location);
  }
  throw error;
}

Install with Tessl CLI

npx tessl i tessl/npm-mdx-js--mdx