SWC Plugin
swc-plugin-exodra is a native Rust/Wasm SWC plugin that compiles Exodra JSX for
SWC-based toolchains — Next.js's default compiler, @swc/jest, swc-loader —
which cannot run Babel plugins. It is a port of @exodra/babel-plugin-schema,
the same dialect in Rust.
:::note "mode" is optional, and "schema" is the only value
An omitted key selects "schema", and writing "mode": "schema" is what the
samples below do. Any other value — "legacy" included — is a compile error
naming the value.
:::
Installation
npm install --save-dev swc-plugin-exodra
The published package ships a prebuilt .wasm. To build from source you need the
Rust toolchain and the wasm32-wasip1 target:
rustup target add wasm32-wasip1
npm run build
Usage
.swcrc / @swc/core
{
"jsc": {
"parser": { "syntax": "typescript", "tsx": true },
"experimental": {
"plugins": [["swc-plugin-exodra", { "mode": "schema" }]]
}
}
}
Next.js
// next.config.js
module.exports = {
experimental: {
swcPlugins: [['swc-plugin-exodra', { mode: 'schema' }]],
},
};
Options
{
"mode": "schema", // optional — the only value, and the default
"schemaSource": "@exodra/core", // where the schema factory is imported from
"schemaImport": "createExoNamedSchema", // its exported name
"markerName": "exoJsx" // the marker call the plugin compiles away
}
An unreadable config is treated as an empty one with a diagnostic, rather than
in silence: the keys below "mode" decide what the emitted imports name, and a
config that was quietly dropped compiles to a module whose imports resolve to
nothing.
What it emits
An exoJsx(…) call in; a module-level schema declaration out, built once for the
process, with every port created under the name written after $.. The machine
that fills the ports is written in TypeScript around it and is not touched.
import { exoJsx } from '@exodra/jsx';
const rowSchema = exoJsx<TRowPorts>(($) => (
<li class="row" data-id={$.id}>
<span class="row__label">{$.label}</span>
<button class="row__btn" onClick={$.toggle} />
</li>
));
import { createExoNamedSchema } from '@exodra/core';
const _s0 = createExoNamedSchema((_b0) => {
_b0.el('li', { class: 'row' }, (_b1) => {
_b1.port('data-id', 'id');
_b1.el('span', { class: 'row__label' }, (_b2) => { _b2.textPort('label'); });
_b1.el('button', { class: 'row__btn' }, (_b2) => { _b2.eventPort('click', 'toggle'); });
});
});
const rowSchema = _s0;
There is no hoisting switch: every backend indexes its prepared plan by the schema's ports, so a schema rebuilt per render is a different program, not a slower one.
Parity with the Babel plugin
@exodra/babel-plugin-schema is the specification, and this plugin compiles the
same dialect to the same output, up to SWC's own codegen formatting (arrow
spacing, quote style). In the last column RowPorts is rowSchema.ports and on is the registrar withExoHandlers(m, (on) => …) hands a machine over rowSchema.
| written | schema call | filled by the machine with |
|---|---|---|
class="row", tabindex={0}, disabled | folded into the markup | — |
data-id={$.id} | port("data-id", "id") | c.attr(RowPorts.id, value) |
<span>{$.label}</span> | textPort("label") | c.text(RowPorts.label, value) |
onClick={$.toggle} | eventPort("click", "toggle") | on(RowPorts.toggle, handler) |
on:dblclick={$.edit} | eventPort("dblclick", "edit") | on(RowPorts.edit, handler) |
ref={$.box} | refPort("box") | — |
unsafeHtml={$.body} | childrenPort("body") | c.unsafeHtml(RowPorts.body, markup) |
<$.rows /> | childrenPort("rows") | c.one, c.list, a createExoChildrenReconciler reconciler, or the port methods |
Everything else is a compile error naming the spelling that would have worked — there is no runtime under this JSX to defer a decision to. The full dialect, including every refusal, is in the JSX guide.
Version compatibility
An SWC Wasm plugin is tied to the swc_core version it was built against, which
must be compatible with your @swc/core / Next.js version. A mismatch fails to
load with "ensure the version of swc_core … is compatible with the host
runtime". Rebuild (or upgrade) the plugin against a matching swc_core when you
upgrade SWC.
If you would rather not manage that, use the Babel pipeline:
under Next.js, adding a babel.config.js with presets: ['exodra'] opts the
project into Babel and disables the SWC transform.