# SWC Plugin

[SWC](https://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools.

If you're using SWC in your project, you can opt for the `@lingui/swc-plugin`. This plugin, designed for SWC, is a Rust version of [Lingui Macros](https://lingui.dev/ref/macro.md).

[![npm-version](https://img.shields.io/npm/v/@lingui/swc-plugin?logo=npm\&cacheSeconds=1800)](https://www.npmjs.com/package/@lingui/swc-plugin) [![npm-downloads](https://img.shields.io/npm/dt/@lingui/swc-plugin?cacheSeconds=500)](https://www.npmjs.com/package/@lingui/swc-plugin)

## SWC Compatibility[​](#swc-compatibility "Direct link to SWC Compatibility")

SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions [is not guaranteed](https://github.com/swc-project/swc/issues/5060). You need to choose an appropriate version of the `@lingui/swc-plugin` to match the compatible `@swc/core` version.

tip

It is recommended to check the [plugins.swc.rs](https://plugins.swc.rs/) site to find the compatible version.

## Installation[​](#installation "Direct link to Installation")

Install `@lingui/swc-plugin` as a development dependency:

* npm
* Yarn
* pnpm

```
npm install --save-dev @lingui/swc-plugin
```

```
yarn add --dev @lingui/swc-plugin
```

```
pnpm add --save-dev @lingui/swc-plugin
```

To ensure that the resolved version of `@swc/core` is one of the supported versions, you can use the `resolutions` field in the `package.json` file, which is supported by Yarn:

package.json

```
"resolutions": {

  "@swc/core": "1.3.56"

}
```

or `overrides` for >npm\@8.3

package.json

```
"overrides": {

  "@swc/core": "1.3.56"

}
```

## Usage[​](#usage "Direct link to Usage")

Add the following configuration to your [`.swcrc`](https://swc.rs/docs/configuration/swcrc) file:

.swcrc

```
{

  "$schema": "https://json.schemastore.org/swcrc",

  "jsc": {

    "experimental": {

      "plugins": [

        [

          "@lingui/swc-plugin",

          {

            // Additional Configuration

          }

        ]

      ]

    }

  }

}
```

If you use Next.js, add the following to your `next.config.js`:

next.config.js

```
/** @type {import('next').NextConfig} */

const nextConfig = {

  reactStrictMode: true,

  experimental: {

    swcPlugins: [

      [

        "@lingui/swc-plugin",

        {

          // Additional Configuration

        },

      ],

    ],

  },

};



module.exports = nextConfig;
```

## Additional Configuration[​](#additional-configuration "Direct link to Additional Configuration")

### Runtime Modules Configuration[​](#runtime-modules-configuration "Direct link to Runtime Modules Configuration")

You can configure the plugin by passing the `runtimeModules` option. This option is an object that maps runtime module names to their corresponding module paths and export names. It is essential for macros, which rely on referencing the global `i18n` object.

```
[

  "@lingui/swc-plugin",

  {

    "runtimeModules": {

      "i18n": ["@lingui/core", "i18n"],

      "trans": ["@lingui/react", "Trans"]

    }

  }

]
```

For more details, refer to the [Runtime Configuration](https://lingui.dev/ref/conf.md#runtimeconfigmodule) section of the documentation.

### JSX Placeholder Naming in `<Trans>`[​](#jsx-placeholder-naming-in-trans "Direct link to jsx-placeholder-naming-in-trans")

You can configure semantic JSX placeholder names for elements inside `<Trans>` with:

* `jsxPlaceholderAttribute` - custom attribute used to set an explicit placeholder name in JSX (for example, `_t="link"`).
* `jsxPlaceholderDefaults` - default placeholder names per JSX tag.

```
[

  "@lingui/swc-plugin",

  {

    "jsxPlaceholderAttribute": "_t",

    "jsxPlaceholderDefaults": {

      "a": "link",

      "strong": "bold"

    }

  }

]
```

For behavior details and examples, see [`macro.jsxPlaceholderAttribute`](https://lingui.dev/ref/conf.md#macrojsxplaceholderattribute) and [`macro.jsxPlaceholderDefaults`](https://lingui.dev/ref/conf.md#macrojsxplaceholderdefaults).

### Descriptor Fields[​](#descriptor-fields "Direct link to Descriptor Fields")

The `descriptorFields` option controls which message descriptor fields are preserved in the transformed code.

* `"auto"` (default): In production (`NODE_ENV === "production"`), keeps only the `id`. Otherwise, keeps all fields.
* `"all"`: Keeps `id`, `message`, `context`, and `comment`.
* `"id-only"`: Strips everything except `id`. Most optimized for production.
* `"message"`: Keeps `id`, `message`, and `context` (but not `comment`).

For example, to keep `message` and `context` in production builds:

```
[

  "@lingui/swc-plugin",

  {

    "descriptorFields": "message"

  }

]
```

## Examples[​](#examples "Direct link to Examples")

* [React with Vite and SWC](https://github.com/lingui/js-lingui/tree/main/examples/vite-project-react-swc)
* [Next.js with SWC](https://github.com/lingui/js-lingui/tree/main/examples/nextjs-swc)

info

If you would like to suggest a new feature or report a bug, please [open an issue](https://github.com/lingui/swc-plugin/issues) on the GitHub repository.