Конфигурация esbuild

MDX — это расширение Markdown, которое позволяет интегрировать JSX-компоненты прямо в Markdown-документы. Для сборки проектов с MDX часто используют esbuild из-за его высокой скорости и гибкой системы плагинов. Настройка esbuild для работы с MDX требует понимания нескольких ключевых аспектов: трансформации MDX в JSX, интеграции с React-компонентами и обработки зависимостей.

Установка необходимых пакетов

Для начала нужно установить основные зависимости:

npm install esbuild @mdx-js/esbuild @mdx-js/react react react-dom

esbuild — инструмент для быстрого бандлинга и трансформации.
@mdx-js/esbuild — плагин, который позволяет esbuild обрабатывать .mdx файлы.
@mdx-js/react — библиотека для рендеринга MDX с React.

Базовая конфигурация esbuild

Простейший пример сборки MDX с esbuild выглядит следующим образом:

const esbuild = require('esbuild');
const { mdx } = require('@mdx-js/esbuild');

esbuild.build({
  entryPoints: ['src/index.mdx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [mdx()],
  loader: {
    '.js': 'jsx',
    '.mdx': 'jsx'
  },
  define: {
    'process.env.NODE_ENV': '"production"'
  },
  minify: true,
  sourcemap: true,
}).catch(() => process.exit(1));

Ключевые моменты:

plugins: [mdx()] подключает плагин MDX, который конвертирует .mdx в JSX.
loader указывает esbuild, как обрабатывать файлы с конкретными расширениями.
define позволяет задавать глобальные переменные окружения на этапе сборки.
bundle: true объединяет все зависимости в один файл.

Настройка JSX

MDX использует JSX для рендеринга компонентов внутри Markdown. В esbuild нужно убедиться, что:

jsxFactory: 'React.createElement',
jsxFragment: 'React.Fragment',

Эти опции гарантируют корректное преобразование JSX в JavaScript. Полная конфигурация может выглядеть так:

esbuild.build({
  entryPoints: ['src/index.mdx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [mdx()],
  loader: {
    '.js': 'jsx',
    '.mdx': 'jsx'
  },
  define: { 'process.env.NODE_ENV': '"production"' },
  jsxFactory: 'React.createElement',
  jsxFragment: 'React.Fragment',
  sourcemap: true
});

Интеграция с React

MDX-файлы могут импортировать и использовать React-компоненты напрямую:

import { Button } from './Button';

# Заголовок MDX

Для корректного рендеринга MDX в React необходимо использовать компонент MDXProvider:

import React from 'react';
import ReactDOM from 'react-dom';
import { MDXProvider } from '@mdx-js/react';
import App from './App.mdx';

ReactDOM.render(
  
    
  ,
  document.getElementById('root')
);

MDXProvider позволяет переопределять стандартные теги Markdown (h1, p, a и т.д.) на свои React-компоненты, создавая гибкую систему кастомизации.

Обработка статики и других ресурсов

Если в MDX используются изображения, CSS или другие ресурсы, их нужно настроить через loader:

loader: {
  '.js': 'jsx',
  '.mdx': 'jsx',
  '.png': 'file',
  '.jpg': 'file',
  '.css': 'css'
}

file — копирует файл в директорию сборки и возвращает путь.
css — позволяет импортировать CSS в JavaScript, если подключен соответствующий плагин.

Параметры плагина @mdx-js/esbuild

Плагин MDX имеет несколько важных опций:

jsxImportSource — указывает, откуда брать JSX-фабрику (обычно react).
providerImportSource — определяет источник MDXProvider.
remarkPlugins и rehypePlugins — подключают плагины для обработки Markdown и HTML.

Пример использования плагинов:

const remarkGfm = require('remark-gfm');

esbuild.build({
  entryPoints: ['src/index.mdx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [mdx({ remarkPlugins: [remarkGfm] })],
});

remark-gfm добавляет поддержку расширений GitHub Flavored Markdown, таких как таблицы и чекбоксы.

Производительность и оптимизация

Incremental builds: esbuild поддерживает режим watch для быстрой пересборки при изменении файлов.
Tree shaking: MDX-плагин совместим с tree shaking, поэтому неиспользуемый код удаляется при сборке.
Sourcemaps: включение sourcemap: true облегчает отладку MDX-компонентов.

Совместная работа с TypeScript

Для проектов на TypeScript добавляют tsconfig.json и используют загрузчик .ts и .tsx:

loader: {
  '.ts': 'ts',
  '.tsx': 'tsx',
  '.mdx': 'jsx'
}

Важно: MDX-файлы всегда компилируются в JSX, поэтому .mdx можно указывать как jsx для совместимости с TypeScript и React.