Настройка JSX pragma

JSX в библиотеке Atomico играет ключевую роль при создании компонентов, но его использование требует понимания механизма JSX pragma. В отличие от React, где JSX автоматически трансформируется в вызовы React.createElement, Atomico использует собственный pragma, позволяющий напрямую управлять созданием виртуальных элементов и интеграцией с реактивной системой библиотеки.

Принцип работы JSX pragma

JSX pragma — это директива, которая сообщает транспилятору (например, Babel или TypeScript), какой метод использовать для преобразования JSX-синтаксиса в вызовы JavaScript-функций. В Atomico стандартным pragma является h:

/** @jsx h */
import { h } from 'atomico';

Здесь:

  • /** @jsx h */ — специальная комментарий-директива, активная при трансформации JSX.
  • h — функция, создающая виртуальный DOM-элемент для Atomico.
  • Все JSX-выражения после этой директивы будут компилироваться в вызовы h.

Например, следующий JSX:

<div class="container">
    <p>Привет, Atomico!</p>
</div>

Компилируется в:

h("div", { class: "container" }, h("p", null, "Привет, Atomico!"));

Настройка через Babel

Babel предоставляет гибкость для глобальной настройки pragma, чтобы не вставлять комментарий в каждый файл. Для этого используется плагин @babel/plugin-transform-react-jsx с указанием pragma:

{
  "plugins": [
    ["@babel/plugin-transform-react-jsx", { "pragma": "h" }]
  ]
}

При такой конфигурации все JSX в проекте автоматически будет использовать h из Atomico без явного комментария в каждом файле.

Настройка через TypeScript

В TypeScript pragma управляется через опцию jsxFactory в tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "h"
  }
}
  • "jsx": "react" — указывает компилятору, что необходимо обрабатывать JSX.
  • "jsxFactory": "h" — указывает, что JSX нужно трансформировать в вызовы функции h из Atomico.

Также можно использовать jsxImportSource для автоматического импорта функции:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "atomico"
  }
}

В этом случае TypeScript сам вставляет импорт h из Atomico и не требует явного комментария в файле.

Пользовательские pragma

Atomico поддерживает замену стандартной функции h на пользовательскую. Это полезно при создании оберток или расширении функциональности JSX. Для этого достаточно импортировать свою функцию и указать pragma:

/** @jsx customH */
import { customH } from './custom-h';

Все JSX-компоненты будут использовать customH вместо стандартного h, что позволяет, например, добавлять автоматическую обработку атрибутов или внедрять дополнительные обертки для компонентов.

Совместимость с сторонними инструментами

Atomico интегрируется с большинством современных сборщиков:

  • Webpack: используется обычная конфигурация Babel или TypeScript для обработки JSX. Важно, чтобы настройка pragma соответствовала используемому транспилятору.
  • Vite: поддерживает pragma через esbuild или через плагин @vitejs/plugin-react, где можно переопределить jsxFactory.
  • Rollup: аналогично, pragma настраивается через Babel или TypeScript-плагины.

Практические рекомендации

  • Для больших проектов рекомендуется глобальная настройка pragma через Babel или TypeScript, чтобы избежать дублирования комментариев /** @jsx h */.
  • При создании собственных JSX-функций использовать пользовательские pragma только в отдельных модулях, чтобы не ломать стандартное поведение.
  • Проверять совместимость с инструментами сборки, особенно если используются старые версии Babel или TypeScript, которые могут не поддерживать опцию jsxImportSource.

Преимущества правильной настройки

  1. Оптимизация кода: JSX-трансформация напрямую в h позволяет уменьшить накладные расходы.
  2. Гибкость: можно легко подменять функцию создания элементов для специальных нужд.
  3. Совместимость с TypeScript: корректная настройка pragma обеспечивает статическую проверку типов для JSX-компонентов Atomico.
  4. Удобство поддержки: единая настройка pragma упрощает поддержку больших кодовых баз и позволяет избежать ошибок при компиляции.

Настройка JSX pragma является фундаментальным шагом для эффективного использования Atomico. Правильная конфигурация позволяет использовать все возможности реактивной модели библиотеки, оптимизировать производительность и упростить масштабирование проекта.

Оглавление