unpeel-swc-plugin

> ⚠️ EXPERIMENTAL: SWC plugins have strict version compatibility requirements. This is a template/starting point that requires version alignment for your specific Next.js version.

SWC plugin that adds data-unpeel-* attributes to JSX elements for source location tracking. This is a Rust/WASM alternative to the JavaScript-based webpack plugin, offering faster transformation times.

Important: Version Compatibility

SWC plugins are NOT backward compatible. You must match:
- swc_core version in Cargo.toml
- @swc/core version in your Next.js project
- Rust nightly version

Use the official compatibility tool: https://plugins.swc.rs

1. Select your framework (Next.js) and version
2. Find the compatible swc_core version
3. Update Cargo.toml accordingly

$3

This template is configured for:
- swc_core = "0.100" → works with @swc/core@1.7.x and next@15.0.0-canary.117+

Check SWC version compatibility docs for the full matrix.

Prerequisites

1. Rust toolchain: Install via rustup
``bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
`

2. WASM target: Add the WebAssembly target
`bash
rustup target add wasm32-wasip1
`

3. SWC CLI (optional, for scaffolding):
`bash
cargo install swc_cli
`

Building

`bash
cd packages/unpeel-swc-plugin

Build the plugin

cargo build --release --target wasm32-wasip1

The output file will be:

target/wasm32-wasip1/release/unpeel_swc_plugin.wasm

`

Usage with Next.js

1. Copy the built .wasm file to your project or publish to npm

2. Configure in next.config.js:

`js
/* @type {import('next').NextConfig} /
const nextConfig = {
experimental: {
swcPlugins: [
// Path to the .wasm file (or package name if published to npm)
['./unpeel_swc_plugin.wasm', {
// Optional: directories to skip
skipDirs: ['components/ui']
}]
]
}
}

module.exports = nextConfig
`

Important: Remove the webpack-based UnpeelPlugin when using the SWC plugin - don't use both!

Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| skipDirs | string[] | [] | Directories to skip processing (relative paths) |

What it does

The plugin transforms JSX elements by adding a data-unpeel JSON attribute with source location and component info:

Input:
`jsx

Click me

`

Output:
`jsx
onClick={handleClick}
variant="outline"
data-unpeel='{"file":"src/app/page.tsx","line":15,"tag":"Button","lineEnd":17,"component":"@/components/ui/button"}'
>
Click me

`

Data Format

The data-unpeel attribute contains a JSON object with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| file | string | Relative file path |
| line | number | Start line number (1-indexed) |
| tag | string | Element or component name |
| lineEnd | number | End line number (if element has closing tag) |
| component | string | Import source path (for imported components only) |

This format is compatible with the Unpeel Data Layer API, allowing direct use of file and line for queries without parsing.

Performance

SWC plugins run during the parsing phase, before bundling. This is typically 10-100x faster than JavaScript-based webpack loaders for large codebases.

Development

`bash


Check for errors without building

cargo check

Run tests

cargo test

Build in debug mode (faster compilation, slower runtime)

cargo build --target wasm32-wasip1
`

Troubleshooting

$3

SWC plugin ecosystem is fast-moving. Check https://plugins.swc.rs for the correct version combinations.

$3

`bash
rustup target add wasm32-wasip1
`

$3

- Ensure your Next.js version matches the swc_core version
- Check that the path to the .wasm file is correct
- SWC plugins only work in development by default

$3

- Check if the file is in a skipped directory
- Ensure the file extension is .jsx, .tsx, .js, or .ts`
- Verify the element isn't a void element (img, input, etc.)

Why use this instead of the Webpack plugin?

| Aspect | Webpack Plugin | SWC Plugin |
|--------|---------------|------------|
| Speed | ~1x | ~10-100x faster |
| Language | JavaScript | Rust (compiled to WASM) |
| Compatibility | Works everywhere | Requires version matching |
| Maintenance | Easier | Requires Rust knowledge |

Recommendation: Use the Webpack plugin unless you have large codebases where build performance is critical.

License

MIT