SWC Plugin Compatibility Explanation

> [!IMPORTANT]
> Starting from [`swc_core@47`](https://plugins.swc.rs/versions/range/768), (`@lingui/swc-plugin@5.10.1`) Wasm plugins are now compatible between @swc/core versions to some extent. Read more [here](https://swc.rs/docs/plugin/ecmascript/compatibility#make-your-plugin-compatible).
>
> This doc was prepared for versions prior `swc_core@47`. With a newer version it shouldn't be a case anymore, however we have not tested how it behaves with newer AST layouts as at the time of writing no release including such changes was available yet.

SWC plugin support is still **experimental**. The plugin API does **not follow semantic versioning**.
If a newer version of SWC introduces changes to the AST layout, a plugin compiled with an older version may break during an execution.

This is the main reason why SWC plugin support is considered experimental.

That said, the **Plugin API itself and existing plugin implementations are battle-tested** and can be safely used in production—*as long as version compatibility is handled carefully*.

If you decide to use SWC with plugins, please follow the rules below to avoid unexpected build failures.

---

## TL;DR; Rules to avoid build breakage

1. **Choose and pin an exact plugin version** that is compatible with your runtime
(see below for how to determine runtime compatibility).

2. **Do not automatically bump `@lingui/swc-plugin` to the latest version.**
Always check the release notes first.

* If the release contains a `swc-core` bump, upgrading **will break** compatibility with older runtimes.
* If a new plugin feature was released *after* a `swc-core` bump, you will need to upgrade your runtime to use that feature.
* `@lingui/swc-plugin` **does not need to match** the versions of other `@lingui/*` packages.
It follows its own versioning scheme (e.g. all `5.*` plugin versions are compatible with `@lingui/core@5.*`).

3. **Do not automatically bump your runtime** (`next`, `rspack`, `@swc/core`, etc.).
Check the runtime’s release notes first.

* Runtimes may bump the underlying `swc-core` in **minor or even patch releases**.
* If your build suddenly fails with one of the errors listed below, check the compatibility table and select a matching plugin version.

## Symptoms

If you see errors like the following in your build logs:

> `failed to invoke plugin on 'Some("/app/src/proxy.ts")'`

> `failed to run Wasm plugin transform. Please ensure the version of swc_core used by the plugin is compatible with the host runtime.`

> `LayoutError called Result::unwrap()`

You are very likely using an **incompatible plugin version**.

## A bit more context

SWC uses [**Rkyv**](https://rkyv.org/) to transfer the AST (Abstract Syntax Tree, they way how the code is presented for the transformation plugins) from the core to the plugin.
You don’t need to understand the internals, but one thing is important:

> Both SWC core and the plugin must agree on the **exact memory layout** of the AST.

If the AST structure changes (for example, a new field is added to a node), older plugins can no longer read the data correctly.
This layout cannot be negotiated at runtime - it must be known **at compile time** by both the core and the plugin.

Because of this, every SWC plugin must be built with a `swc-core` version that is compatible with the one used by the runtime.

SWC does not change the AST layout in every release, but it *does* happen periodically (e.g. when new ECMAScript features are added or internal bugs are fixed).
As a result, there are [**compatibility ranges**](https://plugins.swc.rs/versions/range) of `swc-core` versions that work together, and others that do not.

## Runtimes explained

By *runtime*, we mean the tool that executes SWC and its plugins, such as **Next.js**, **Rspack**, or `@swc/core`.

SWC exists in two forms:

* `swc-core` — the **Rust crate** - similar to NPM package but in the Rust ecosystem with Rust sources
* `@swc/core` — the **JavaScript wrapper** around precompiled Rust binaries published on NPM

Some runtimes (like Next.js or Rspack) **do not use `@swc/core` at all**.
Instead, they depend directly on the Rust crate and ship their own binaries with SWC embedded.

This means:

* You **cannot** control or bump `swc-core` in those runtimes via `package.json`
* Plugin compatibility depends entirely on which `swc-core` version the runtime ships

## How we handle this in Lingui

There is currently **no official solution from the SWC team** for plugin compatibility, and it does not appear to be a top priority upstream.

* We bump **one incompatible `swc-core` version at a time** - This ensures users can always find a plugin version compatible with their runtime
* We keep an up-to-date [compatibility table](https://github.com/lingui/swc-plugin/tree/main/packages/lingui-macro#compatibility) in the README, showing which `swc_core` version each plugin release was built with. Once you know the `swc_core` version, finding a compatible runtime is straightforward.

This works reasonably well today because the plugin itself is relatively stable.

However, it becomes more challenging when introducing new features:
to use such features, users may need to upgrade their runtime to a newer `swc-core`, which is not always possible.

## Finding a compatible version

The best way to find a compatible version is to use https://plugins.swc.rs/.

1. Select your runtime (e.g. `next`)
2. Select the runtime version (e.g. `next@15.0.1`)
3. The site will show which plugin versions (if any) are compatible

You can also use the **reverse approach** via the compatibility table in the README.

**Example:**
Plugin `5.8.0` was compiled with `swc_core@45.0.2`.
According to the linked compatibility page, this version is compatible with `next@16.0.0 – 16.0.10`.

---

If you treat plugin and runtime versions as a **locked pair**, SWC plugins can be used reliably in production.

## What to do if there is no compatible version for your runtime?

That's happend! We don't recieve a notification when new incompatible `swc_core` version released. If you run into this situation, please let as know, or even better, open a PR with a version bump. We’ll be happy to review and merge it!

The issue does not identify a documentation file; first locate the SWC plugin compatibility explanation and the README compatibility table mentioned in the text. Verify the runtime/plugin guidance, compatibility ranges, links, and examples, and consider the work complete when the intended explanation is placed in the appropriate documentation with accurate references.

Written by the indexing model from the issue text.