An official SWC plugin can be used for SSR and easier debugging experience in SWC-powered projects, like Next.js or Vite with vite-react-swc plugin.

The plugin has the same functionality as the built-in babel-plugin. It provides all Units with unique SIDs (Stable Identifier) and name, as well as other debug information.

Installation

Install @effector/swc-plugin using your preferred package manager.

npm install -ED @effector/swc-plugin

Versioning

To avoid compatibility issues caused by breaking changes in SWC or Next.js, this plugin publishes different ‘labels’ for different underlying @swc/core. Refer to the table below to choose the correct plugin version for your setup.

For more information on compatibility, refer to the SWC documentation on Selecting the SWC Version and interactive compatibility table on SWC website.

Usage

To use the plugin, simply add it to your tool’s configuration.

Next.js

If you’re using the Next.js Compiler powered by SWC, add this plugin to your next.config.js.

const nextConfig = {
  experimental: {
    // even if empty, pass an options object `{}` to the plugin
    swcPlugins: [["@effector/swc-plugin", {}]],
  },
};

You’ll also need to install the official @effector/next bindings to enable SSR/SSG.

.swcrc

Add a new entry to jsc.experimental.plugins option in your .swcrc.

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

Configuration

factories

Specify an array of module names or files to treat as custom factories. When using SSR, factories is required for ensuring unique SIDs across your application.

Formulae

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

• Type: string[]
• Default: []

If you provide a relative path (starting with ./), the plugin treats it as a local factory relative to your project’s root directory. These factories can only be imported using relative imports within your code.

Otherwise, if you specify a package name or TypeScript alias, it’s interpreted as an exact import specifier. You must use such import exactly as specified in configuration.

Examples

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

import { createStore } from "effector";

/* createBooleanStore is a factory */
export const createBooleanStore = () => createStore(true);

import { createBooleanStore } from "../factory";

const $boolean = createBooleanStore(); /* Treated as a factory! */

debugSids

Append the full file path and Unit name to generated SIDs for easier debugging of SSR issues.

Formulae

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

• Type: boolean
• Default: false

hmr

Enable Hot Module Replacement (HMR) support to clean up links, subscriptions and side effects managed by Effector. This prevents double-firing of Effects and watchers.

Formulae

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

• Type: "es" | "cjs" | false
  • "es": Use import.meta.hot HMR API in bundlers that are ESM-compliant, like Vite and Rollup
  • "cjs": Use module.hot HMR API in bundlers that rely on CommonJS modules, like Webpack, Next.js or Metro (React Native)
  • false: Disable Hot Module Replacement
• Default: false

addNames

Add names to Units when calling factories (like createStore or createDomain). This is helpful for debugging during development and testing, but its recommended to disable it for minification.

Formulae

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

• Type: boolean
• Default: true

addLoc

Include location information (file paths and line numbers) for Units and factories. This is useful for debugging with tools like effector-logger.

Formulae

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

• Type: boolean
• Default: false

forceScope

Inject forceScope: true into all hooks or @effector/reflect calls to ensure your app always uses Scope during rendering. If Scope is missing, an error will be thrown, eliminating the need for /scope or /ssr imports.

Formulae

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

• Type: boolean | { hooks: boolean, reflect: boolean }
• Default: false

hooks

Enforces all hooks from effector-react and effector-solid, like useUnit and useList, to use Scope in runtime.

reflect

For @effector/reflect users, enforces all components created with reflect library use Scope in runtime.

transformLegacyDomainMethods

When enabled (default), this option transforms Unit creators in Domains, like domain.event() or domain.createEffect(). However, this transformation can be unreliable and may affect unrelated code. If that’s the case for you, disabling this option can fix these issues.

Disabling this option will stop adding SIDs and other debug information to these unit creators. Ensure your code does not depend on domain methods before disabling.

Formulae

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

• Type: boolean
• Default: true