Официальный SWC плагин может быть использован для SSR и более удобного опыта отладки в проектах, использующих SWC, таких как Next.js или Vite с плагином vite-react-swc.

Плагин обладает той же функциональностью, что и встроенный babel-plugin.
Он предоставляет всем Юнитам уникальные сиды (Стабильные Идентификаторы) и имена, а также другую отладочную информацию.

Установка

Установите @effector/swc-plugin с помощью предпочитаемого менеджера пакетов.

npm install -ED @effector/swc-plugin

Версионирование

Чтобы избежать проблем с совместимостью, вызванных критическими изменениями в SWC или Next.js, этот плагин публикует разные ‘метки’ для разных версий @swc/core. Обратитесь к таблице ниже, чтобы выбрать правильную версию плагина для вашей настройки.

Для получения дополнительной информации о совместимости обратитесь к документации SWC по Выбору версии SWC и интерактивной таблице совместимости на сайте SWC.

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

Чтобы использовать плагин, просто добавьте его в конфигурацию вашего инструмента.

Next.js

Если вы используете Next.js Compiler, работающий на SWC, добавьте этот плагин в ваш next.config.js.

const nextConfig = {
  experimental: {
    // даже если пусто, передайте объект опций `{}` в плагин
    swcPlugins: [["@effector/swc-plugin", {}]],
  },
};

Вам также нужно установить официальные @effector/next привязки, чтобы включить SSR/SSG.

.swcrc

Добавьте новую запись в опцию jsc.experimental.plugins в вашем .swcrc.

{
  "$schema": "https://json.schemastore.org/swcrc",
  "jsc": {
    "experimental": {
      "plugins": [["@effector/swc-plugin", {}]]
    }
  }
}

Конфигурация

factories

Укажите массив имен модулей или файлов, которые следует рассматривать как пользовательские фабрики. При использовании SSR фабрики необходимы для обеспечения уникальных SID по всему вашему приложению.

Формула

["@effector/swc-plugin", { "factories": ["./path/to/factory", "factory-package"] }]

• Тип: string[]
• По умолчанию: []

Если вы предоставляете относительный путь (начинающийся с ./), плагин рассматривает его как локальную фабрику относительно корневой директории вашего проекта. Эти фабрики могут быть импортированы только с использованием относительных импортов в вашем коде.

В противном случае, если вы указываете имя пакета или алиас TypeScript, это интерпретируется как точный спецификатор импорта. Вы должны использовать такой импорт точно так, как указано в конфигурации.

Примеры

// конфигурация
["@effector/swc-plugin", { "factories": ["./src/factory"] }]

// файл: /src/factory.ts
import { createStore } from "effector";

/* createBooleanStore — это фабрика */
export const createBooleanStore = () => createStore(true);

// файл: /src/widget/user.ts
import { createBooleanStore } from "../factory";

const $boolean = createBooleanStore(); /* Рассматривается как фабрика! */

debugSids

Добавляет полный путь к файлу и имя Юнита к сгенерированным сидам для более удобной отладки проблем с SSR.

Формула

["@effector/swc-plugin", { "debugSids": false }]

• Тип: boolean
• По умолчанию: false

hmr

Включите поддержку Hot Module Replacement (HMR) для очистки связей, подписок и побочных эффектов, управляемых Effector. Это предотвращает двойное срабатывание эффектов и наблюдателей.

Формула

["@effector/swc-plugin", { "hmr": "es" }]

• Тип: "es" | "cjs" | "none"
  • "es": Использует API HMR import.meta.hot в сборщиках, соответствующих ESM, таких как Vite и Rollup
  • "cjs": Использует API HMR module.hot в сборщиках, использующих CommonJS модули, таких как Webpack и Next.js
  • "none": Отключает Hot Module Replacement.
• По умолчанию: none

addNames

Добавляет имена к Юнитам при вызове фабрик (таких как createStore или createDomain). Это полезно для отладки во время разработки и тестирования, но рекомендуется отключать это для минификации.

Формула

["@effector/swc-plugin", { "addNames": true }]

• Тип: boolean
• По умолчанию: true

addLoc

Включает информацию о местоположении (пути к файлам и номера строк) для Юнитов и фабрик. Это полезно для отладки с такими инструментами, как effector-logger.

Формула

["@effector/swc-plugin", { "addLoc": false }]

• Тип: boolean
• По умолчанию: false

forceScope

Внедряет forceScope: true во все хуки или вызовы @effector/reflect, чтобы гарантировать, что ваше приложение всегда использует Scope во время рендеринга. Если Scope отсутствует, будет выброшена ошибка, что устраняет необходимость в импортах /scope или /ssr.

Формула

["@effector/swc-plugin", { "forceScope": false }]

• Тип: boolean | { hooks: boolean, reflect: boolean }
• По умолчанию: false

hooks

Принудительно заставляет все хуки из effector-react и effector-solid, такие как useUnit и useList, использовать Scope в runtime.

reflect

Для пользователей @effector/reflect принудительно заставляет все компоненты, созданные с помощью библиотеки reflect, использовать Scope в runtime.

transformLegacyDomainMethods

Если включено (по умолчанию), эта опция преобразует создатели Юнитов в Доменах, такие как domain.event() или domain.createEffect(). Однако это преобразование может быть ненадежным и может повлиять на несвязанный код. Если это ваш случай, отключение этой опции может исправить эти проблемы.

Отключение этой опции остановит добавление SID и другой отладочной информации к этим создателям юнитов. Убедитесь, что ваш код не зависит от методов домена перед отключением.

Формула

["@effector/swc-plugin", { "transformLegacyDomainMethods": true }]

• Тип: boolean
• По умолчанию: true