Evaluate API

Evaluate API является одним из ключевых инструментов библиотеки MDX, предоставляя возможность динамически интерпретировать и выполнять MDX-контент в среде JavaScript. Основная цель API — преобразование текста MDX в полноценные React-компоненты с поддержкой JSX и всех возможностей MDX.

Основные функции Evaluate API

1. evaluate

Функция evaluate принимает на вход строку с MDX-кодом и возвращает объект, содержащий готовые React-компоненты и метаданные. В типичном случае результат работы функции содержит:

  • Content — React-компонент, который можно напрямую использовать в JSX.
  • frontmatter — объект с метаданными документа (если они присутствуют в MDX через YAML-блок).
  • scope — объект с дополнительными переменными, переданными в контекст MDX.

Пример базового вызова:

import { evaluate } from '@mdx-js/mdx';

const mdxSource = `
---
title: "Пример MDX"
---

# Заголовок

Текст с **жирным** выделением и JSX-компонентом: <Button>Click me</Button>
`;

const result = await evaluate(mdxSource, { scope: { Button } });

const App = () => <result.Content />;

В этом примере Button передан в scope, что позволяет использовать его внутри MDX-контента.

Настройка Evaluate API

Опции функции evaluate позволяют управлять процессом компиляции MDX:

  • scope — объект с переменными и компонентами, доступными внутри MDX.

  • development — булевый флаг, который включает подробные предупреждения и отладочную информацию.

  • outputFormat — формат выходного результата. Поддерживаются значения:

    • 'function-body' — возвращает функцию, содержащую тело React-компонента.
    • 'program' — возвращает полностью скомпилированный код, который можно выполнять через eval или сборщик.

Пример с расширенными опциями:

const result = await evaluate(mdxSource, {
  scope: { Button },
  development: true,
  outputFormat: 'function-body'
});

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

MDX поддерживает frontmatter — метаданные, определяемые в верхней части документа через YAML. Evaluate API автоматически извлекает эти данные и делает их доступными в результате.

Пример:

---
title: "Документ MDX"
author: "Иван Иванов"
---

# Содержание документа

В коде:

const { Content, frontmatter } = await evaluate(mdxSource);
console.log(frontmatter.title); // "Документ MDX"
console.log(frontmatter.author); // "Иван Иванов"

Интеграция с React-компонентами

Evaluate API позволяет интегрировать MDX с React, передавая компоненты через scope или глобально через components. Это дает возможность использовать MDX как динамическую разметку в приложениях.

Пример передачи компонентов через scope:

const scope = {
  Button: (props) => <button {...props} />
};

const result = await evaluate(mdxSource, { scope });

const App = () => <result.Content />;

Теперь любой компонент <Button /> в MDX будет рендериться через переданную функцию.

Поддержка JSX и динамических выражений

MDX позволяет вставлять JSX внутри текста и использовать любые JavaScript-выражения в фигурных скобках {}. Evaluate API выполняет их в контексте scope:

# Счётчик
{Array.from({ length: 5 }).map((_, i) => <li key={i}>Элемент {i+1}</li>)}

В этом примере создается список <li> с динамическими значениями, который корректно рендерится через React.

Особенности работы с асинхронными компонентами

Если MDX-контент использует асинхронные компоненты или данные, Evaluate API поддерживает их через стандартный React-подход. Например, можно использовать React.Suspense:

const AsyncComponent = React.lazy(() => import('./AsyncComponent'));

const result = await evaluate(mdxSource, { scope: { AsyncComponent } });

const App = () => (
  <React.Suspense fallback={<div>Загрузка...</div>}>
    <result.Content />
  </React.Suspense>
);

Ошибки и отладка

При компиляции MDX Evaluate API может выбрасывать ошибки синтаксиса или недоступных компонентов. Рекомендуется включать development: true для получения расширенных сообщений об ошибках и контекста.

Типичные ошибки:

  • ReferenceError — компонент или переменная не переданы в scope.
  • SyntaxError — некорректный MDX/JSX.
  • TypeError — попытка использовать неподдерживаемый JSX-синтаксис.

Evaluate API делает MDX мощным инструментом для динамического контента, позволяя сочетать текст, JSX и JavaScript в одном месте с высокой степенью контроля над контекстом и компонентами.

Оглавление