Подготовка к деплою

Для работы с MDX необходимо установить соответствующие пакеты через npm или Yarn. Базовый набор включает:

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

или

yarn add @mdx-js/mdx @mdx-js/react

@mdx-js/mdx отвечает за компиляцию MDX в React-компоненты, а @mdx-js/react предоставляет MDXProvider для интеграции с React-приложением.

Конфигурация сборщика

MDX можно интегрировать с различными сборщиками: Webpack, Vite, Next.js. Основная цель — настроить обработку .mdx файлов. Для Webpack пример конфигурации:

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          'babel-loader',
          {
            loader: '@mdx-js/loader',
            /** Опции MDX */
            options: {
              remarkPlugins: [],
              rehypePlugins: []
            }
          }
        ]
      }
    ]
  }
};

Для Vite используется плагин vite-plugin-mdx:

import mdx from 'vite-plugin-mdx';

export default {
  plugins: [mdx()]
};

Подготовка к продакшен-сборке

  1. Компиляция MDX в React-компоненты MDX-файлы можно заранее компилировать для ускорения загрузки и уменьшения веса пакета. Например, скрипт для CLI:
npx @mdx-js/mdx src/content --out-dir src/components/mdx
  1. Минификация кода Использование современных бандлеров автоматически выполняет tree-shaking и минификацию. Для Webpack:
const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [new TerserPlugin()]
  }
};
  1. Оптимизация загрузки стилей Если MDX использует CSS-модули или Styled Components, необходимо убедиться, что стили корректно инкапсулируются и минифицируются. Для Styled Components включается Babel-плагин:
npm install babel-plugin-styled-components --save-dev
{
  "plugins": ["babel-plugin-styled-components"]
}

Использование MDXProvider

MDXProvider позволяет определять, как будут отображаться определённые HTML-теги или компоненты внутри MDX. Для деплоя важно, чтобы все компоненты были импортированы и переданы в MDXProvider:

import { MDXProvider } from '@mdx-js/react';
import CustomHeading from './components/CustomHeading';
import CustomParagraph from './components/CustomParagraph';

const components = {
  h1: CustomHeading,
  p: CustomParagraph
};

function App({ children }) {
  return <MDXProvider components={components}>{children}</MDXProvider>;
}

Это позволяет гарантировать корректное отображение на продакшен-сборке без ошибок из-за отсутствующих компонентов.

Обработка изображений и ассетов

MDX позволяет импортировать изображения напрямую:

import Logo from './logo.png';

export default () => <img src={Logo} alt="Логотип" />;

Для продакшена важно настроить загрузку ассетов через Webpack или Vite с хэшированием:

{
  test: /\.(png|jpg|svg)$/,
  type: 'asset/resource',
  generator: {
    filename: 'assets/[hash][ext][query]'
  }
}

Это предотвращает кэш-проблемы после деплоя.

Превентивное тестирование сборки

Перед деплоем рекомендуется прогонять сборку на локальном сервере:

npm run build
npm run serve

Важные моменты:

  • Проверка всех маршрутов и ссылок внутри MDX.
  • Убедиться, что стили корректно применяются.
  • Контроль размеров бандла после минификации.

Настройка окружений

MDX-файлы часто содержат контент, зависящий от окружения. Для продакшена можно использовать переменные окружения:

const apiUrl = process.env.API_URL;

export default () => <div>API URL: {apiUrl}</div>;

При деплое нужно убедиться, что .env.production корректно считывается сборщиком.

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

MDX активно используется с Headless CMS. Перед деплоем необходимо:

  • Настроить генерацию статических страниц (SSG) или серверный рендеринг (SSR).
  • Убедиться, что данные подтягиваются корректно, и нет пустых компонентов в сборке.

Автоматизация деплоя

MDX-проекты можно деплоить через CI/CD, используя сборку и тестирование перед публикацией. Пример GitHub Actions:

name: Deploy MDX
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - run: npm run deploy

Это гарантирует, что MDX-компоненты корректно компилируются и публикуются на сервер или в CDN.

Оглавление