swc-plugin-compatibility（SWC 插件兼容性）

SWC Plugin Compatibility

If you see errors like these during your build:

failed to invoke plugin on 'Some("/app/src/file.ts")'
failed to run Wasm plugin transform
RuntimeError: out of bounds memory access
LayoutError called Result::unwrap()

This is NOT a bug. You're using an incompatible version of @lingui/swc-plugin with your SWC runtime.

Why This Happens

SWC plugin support is experimental. The plugin API does not follow semantic versioning.

SWC uses Rkyv to transfer the AST between the core and plugins. Both must agree on the exact memory layout of the AST. If the layout changes (e.g., new ECMAScript features), older plugins cannot read the data correctly.

This layout cannot be negotiated at runtime - it must match at compile time.

How to Fix

Step 1: Check the Compatibility Table

Go to the compatibility table and find the plugin version that matches your runtime.

Step 2: Use the Plugin Compatibility Site

For precise matching, use https://plugins.swc.rs/:

1. Select your runtime (e.g., next)
2. Select your runtime version (e.g., next@15.0.1)
3. Find a compatible @lingui/swc-plugin version

Step 3: Pin Your Versions

{
  "devDependencies": {
    "@lingui/swc-plugin": "5.10.0"
  }
}

Use an exact version (no ^ or ~) to prevent accidental upgrades.

Version Compatibility Quick Reference

Important: @lingui/swc-plugin does not need to match other @lingui/* package versions exactly. It follows its own versioning scheme.

Rules to Avoid Build Breakage

1. Pin an exact plugin version compatible with your runtime
2. Don't auto-bump @lingui/swc-plugin - check release notes first
3. Don't auto-bump your runtime (Next.js, Rspack, etc.) - runtimes may bump swc-core in minor/patch releases
4. Check compatibility after any upgrade that touches SWC or the plugin

Understanding Runtimes

By "runtime" we mean the tool executing SWC: Next.js, Rspack, or @swc/core.

Some runtimes (like Next.js) embed SWC directly and don't use @swc/core from npm. This means:

• You cannot control swc-core version via package.json
• Plugin compatibility depends on the runtime's embedded SWC version

Example: Next.js Configuration

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    swcPlugins: [
      ['@lingui/swc-plugin', {
        // Plugin options
      }],
    ],
  },
};

module.exports = nextConfig;

Example:.swcrc Configuration

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

What If No Compatible Version Exists?

If your runtime uses a newer swc-core that no plugin version supports yet:

1. Check for recent plugin releases
2. Open an issue or PR at https://github.com/lingui/swc-plugin