SWC Plugin Compatibility Explanation

[timofei-iatsenko]

Important

Starting from swc_core@47, (@lingui/swc-plugin@5.10.1) Wasm plugins are now compatible between @swc/core versions to some extent. Read more here.

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 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 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 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!