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

Current Configuration

This template is configured for:

• swc_core = "0.100" → works with @swc/[email protected] and [email protected]+

Check SWC version compatibility docs for the full matrix.

Prerequisites

1. Rust toolchain: Install via rustup

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. WASM target: Add the WebAssembly target

   rustup target add wasm32-wasip1

3. SWC CLI (optional, for scaffolding):

   cargo install swc_cli

Building

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:

/** @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:

<Button onClick={handleClick} variant="outline">
  Click me
</Button>

Output:

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

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

# 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

Build errors about version incompatibility

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

"wasm32-wasip1 target not found"

rustup target add wasm32-wasip1

Plugin not loading in Next.js

• 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

Attributes not appearing

• 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