Интеграция с различными сборщиками

MDX сочетает возможности Markdown и JSX, позволяя использовать компоненты React внутри документации, блогов и интерфейсов. Для эффективного применения MDX необходимо корректно интегрировать его с различными сборщиками, такими как Webpack, Vite, Rollup, а также с системами статической генерации вроде Next.js и Gatsby.

Webpack

Для работы MDX с Webpack основной инструмент — это загрузчики (loaders). Стандартная конфигурация включает:

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: '@mdx-js/loader',
            options: {
              // Возможность передавать компоненты
              remarkPlugins: [],
              rehypePlugins: [],
            },
          },
        ],
      },
    ],
  },
};

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

  • @mdx-js/loader преобразует .mdx в валидный JSX.
  • Плагин remarkPlugins позволяет работать с Markdown на более глубоком уровне, например добавлять таблицы, сноски или кастомные синтаксические расширения.
  • rehypePlugins обрабатывает HTML после преобразования Markdown в JSX, что важно для добавления классов, атрибутов или других изменений в структуре документа.

Для интеграции с React необходим babel-loader, чтобы JSX корректно транспилировался.

Vite

Vite использует современный подход, основанный на ESM и быстрой пересборке:

import { defineConfig } from 'vite';
import mdx from '@mdx-js/rollup';

export default defineConfig({
  plugins: [
    mdx({
      remarkPlugins: [],
      rehypePlugins: [],
    }),
  ],
});

Особенности интеграции:

  • MDX в Vite обрабатывается через плагин Rollup (@mdx-js/rollup), что позволяет использовать его в современных проектах с быстрым HMR (Hot Module Replacement).
  • Можно подключать MDX как полноценные компоненты React: import Page from './example.mdx'.
  • Vite автоматически оптимизирует импорты, что делает сборку легкой и быстрой.

Rollup

В проектах на Rollup интеграция MDX строится через плагин:

import mdx from '@mdx-js/rollup';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
  },
  plugins: [
    mdx({
      remarkPlugins: [],
      rehypePlugins: [],
    }),
  ],
};

Особенности:

  • Поддержка ESM обеспечивает tree-shaking и минимизацию кода.
  • Возможность использования MDX для сборки документации и библиотек компонентов.
  • Поддержка remarkPlugins и rehypePlugins идентична Webpack и Vite.

Next.js

Next.js имеет собственную систему обработки MDX через @next/mdx или сторонние библиотеки:

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
});

module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
});

Особенности:

  • MDX можно использовать как страницы Next.js, например: pages/blog.mdx.
  • Поддержка динамического импорта MDX-компонентов через next/dynamic.
  • Интеграция с remark и rehype позволяет создавать кастомные плагины для обработки контента перед рендерингом.

Gatsby

Gatsby использует плагин gatsby-plugin-mdx:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-mdx',
      options: {
        remarkPlugins: [],
        rehypePlugins: [],
        gatsbyRemarkPlugins: [],
      },
    },
  ],
};

Особенности:

  • MDX-файлы автоматически становятся GraphQL-узлами.
  • Легкая интеграция с компонентами Gatsby и React.
  • Возможность создавать динамические страницы из MDX с использованием gatsby-node.js.

Настройка плагинов и расширений

Remark Plugins:

  • remark-math — поддержка математических формул.
  • remark-slug — генерация уникальных идентификаторов для заголовков.
  • remark-autolink-headings — автоматическая генерация ссылок на заголовки.

Rehype Plugins:

  • rehype-highlight — подсветка синтаксиса в коде.
  • rehype-slug — добавление id к заголовкам.
  • rehype-react — рендеринг HTML через компоненты React.

Правильная комбинация этих плагинов позволяет гибко управлять содержимым MDX-документов независимо от сборщика.

Советы по оптимизации

  1. Разделение кода — импортировать MDX как ленивые компоненты для уменьшения размера бандла.
  2. Кеширование — использовать кеш-loader или Vite/Rollup кеш для ускорения пересборки.
  3. Тестирование плагинов — некоторые remark и rehype плагины могут конфликтовать, важно проверять их последовательность.

MDX, при правильной интеграции с выбранным сборщиком, позволяет строить масштабируемые проекты, где документация, блог или интерфейсная часть приложения могут использовать единую систему компонентов и разметки Markdown, полностью совместимую с React.

Оглавление