Миграция с MDX v1 на v2

MDX v2 представляет собой значительное обновление по сравнению с v1, ориентированное на повышение совместимости с современными инструментами экосистемы React и улучшение безопасности. Одним из ключевых изменений является переход на новый синтаксис экспорта и импорта компонентов, а также переработанная система обработки JSX внутри Markdown.

  • ESM вместо CommonJS: MDX v2 полностью поддерживает стандарты ECMAScript Modules. В файлах теперь рекомендуется использовать export вместо module.exports.

  • Явный импорт React: Ранее MDX автоматически инжектировал React в скоуп. В v2 требуется явный импорт при работе с JSX-компонентами:

    import React from 'react';

  • Слоты и компоненты: Поддержка MDXProvider осталась, но обработка компонентов стала более строгой. Любой компонент, используемый внутри MDX, должен быть явно передан через components объект.

Работа с JSX и Markdown

MDX v2 улучшает интероперабельность между JSX и Markdown. Основные моменты:

  • JSX внутри Markdown теперь строго соответствует синтаксису React. Любые нестандартные конструкции, ранее разрешенные MDX v1, теперь могут вызвать ошибки компиляции.

  • Синтаксис кода: блоки с тройными обратными кавычками (```) поддерживают указание языка, но теперь требуется использование валидного имени языка для подсветки и интеграции с инструментами типа rehype-prism.

    ```javascript
const sum = (a, b) => a + b;

  • Inline JSX: элементы можно вставлять прямо в текст, но они должны быть корректно закрыты:

    Это пример <strong>выделенного текста</strong> в середине Markdown.

Система плагинов и обработчиков

MDX v2 отказалась от устаревшей системы плагинов и интегрировалась с современными инструментами экосистемы unified:

  • remark-плагины: для обработки Markdown используются стандартные плагины remark, например, remark-gfm для поддержки GitHub-flavored Markdown.
  • rehype-плагины: обработка HTML и атрибутов стала гибкой. Например, rehype-slug добавляет ID заголовкам для генерации оглавления.
  • Совместимость с Webpack и Vite: новые плагины для MDX v2 обеспечивают корректную загрузку .mdx файлов и оптимизацию сборки.

Обновление конфигурации проекта

Процесс миграции требует изменения конфигурации сборщика и инструментов:

  • Webpack: необходимо заменить устаревший @mdx-js/loader на современный @mdx-js/webpack с поддержкой v2.

    {
  test: /\.mdx$/,
  use: [
    'babel-loader',
    {
      loader: '@mdx-js/loader',
      options: {
        remarkPlugins: [],
        rehypePlugins: []
      }
    }
  ]
}

  • Vite: подключение через плагин vite-plugin-mdx с явным указанием jsxImportSource.

  • Babel: настройка может потребовать добавления плагина @babel/plugin-transform-react-jsx для корректной трансформации JSX внутри MDX.

Работа с компонентами и MDXProvider

MDX v2 усилила строгую типизацию и контроль скоупа:

  • Любой компонент должен быть явно импортирован.

  • MDXProvider используется для глобальной подстановки компонентов:

    import { MDXProvider } from '@mdx-js/react';
import CustomButton from './CustomButton';

const components = {
  button: CustomButton
};

<MDXProvider components={components}>
  <Content />
</MDXProvider>

  • Теперь возможна локальная передача компонентов через components пропс для отдельных страниц или блоков MDX, что повышает модульность и снижает глобальные зависимости.

Новые возможности и улучшения

  • Статическая типизация: благодаря поддержке TypeScript можно объявлять типы для props MDX-компонентов.
  • Улучшенная оптимизация сборки: MDX v2 поддерживает tree-shaking, что позволяет уменьшать размер итогового бандла.
  • Соблюдение стандартов JSX: любая нестандартная конструкция MDX v1, которая ранее могла быть интерпретирована, теперь строго валидируется.

Пошаговая миграция

  1. Обновление зависимостей:

    npm install @mdx-js/react@latest @mdx-js/loader@latest

  2. Проверка импорта React в каждом MDX-файле.

  3. Замена устаревших синтаксисов (export default, автоматический React-инжект) на современные стандарты.

  4. Подключение необходимых remark и rehype плагинов для совместимости с текущей версткой.

  5. Тестирование рендеринга всех страниц с JSX и Markdown.

  6. Обновление сборщиков (Webpack/Vite) для корректной обработки MDX v2 файлов.

Каждое изменение должно быть проверено на уровне сборки и рендеринга, чтобы избежать неожиданного поведения при строгой проверке JSX в новой версии.

Оглавление