Duplicate SWC transform for use client components when React Compiler is disabled

[travzhang]

Link to the code that reproduces this issue

https://github.com/canyon-project/nextjs16-swc-duplicate-compilation

To Reproduce

1. pnpm i
2. npm run build
3. look .swc-plugin-stage-output

Current vs. Expected behavior

After testing the Next.js + Turbopack combination, we observed duplicate identical filenames appearing in the SWC AST during compilation. Our investigation identified that this behavior is inherent to Next.js' compilation workflow.
To address this ambiguity (consistent with Vite's pattern), we propose appending a layer query parameter to the filename passed to SWC (via TransformContext) — e.g., app/page.tsx?layer=app-rsc — to enable SWC plugins to distinguish between these duplicate entries.
For extensibility (aligned with next-swc-loader), we use a named parameter format:

• Use ?layer=value for paths with no existing query string
• Use &layer=... for paths that already contain a query string

Expected behavior

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.0.0: Wed Sep 17 21:41:45 PDT 2025; root:xnu-12377.1.9~141/RELEASE_ARM64_T6000
  Available memory (MB): 16384
  Available CPU cores: 8
Binaries:
  Node: 25.2.1
  npm: 11.6.2
  Yarn: N/A
  pnpm: 10.13.0
Relevant Packages:
  next: 16.1.6 // Latest available version is detected (16.1.6).
  eslint-config-next: N/A
  react: 19.2.3
  react-dom: 19.2.3
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

SWC

Which stage(s) are affected? (Select all that apply)

next build (local)

Additional context

[darshjme-codes]

This is a legitimate architectural challenge for SWC plugins in Next.js App Router. The "duplicate" transforms are actually intentional multiple compilation passes for different execution contexts, but the current TransformContext doesn't expose which pass is which.

Why Files Are Compiled Multiple Times

Next.js App Router compiles files up to 3 times for different layers:

Layer	Purpose	SWC Transforms
app-rsc	React Server Components (server-only)	Remove client code, tree-shake imports
app-client	Client-side bundle	Remove server-only code, bundle browser APIs
app-ssr	Server-side rendering (SSR)	Hybrid: server + client code, React streaming

Example: app/page.tsx with "use client":

1. Pass 1 (app-rsc): Compile for RSC runtime (server)
2. Pass 2 (app-client): Compile for browser bundle
3. Pass 3 (app-ssr): Compile for SSR hydration

Without layer context, SWC plugins see the same filename 2-3 times but can't distinguish which pass is which.

Impact on SWC Plugins

Coverage tools (like Canyon):

• Need to know which layer is being transformed to avoid counting lines 2-3x
• Must correlate source maps across layers
• Can't currently detect if code is server-only or client-only

Code analysis plugins:

• Can't apply layer-specific transforms (e.g., remove console.log only in client bundles)
• Over-count metrics (file complexity, function counts)

Bundle analyzers:

• Can't separate RSC vs client bundle sizes
• Double/triple-count module imports

Proposed Solution: Query Parameter

Add a ?layer=<context> query parameter to TransformContext filenames:

Before:

app/page.tsx  // Compiled 3 times, plugin sees duplicates

After:

app/page.tsx?layer=app-rsc    // RSC layer
app/page.tsx?layer=app-client // Client layer
app/page.tsx?layer=app-ssr    // SSR layer

Implementation:

// In next/build/swc/index.ts (pseudocode)
function transform(filename, source, options) {
  const layer = options.isServer 
    ? (options.isRSC ? 'app-rsc' : 'app-ssr')
    : 'app-client';
  
  const contextFilename = filename.includes('?')
    ? `${filename}&layer=${layer}`
    : `${filename}?layer=${layer}`;
  
  return swc.transform(source, {
    ...options,
    filename: contextFilename // <-- Pass to plugin
  });
}

Precedents

Vite (already does this)

Vite uses query parameters extensively for virtual modules:

src/App.vue?vue&type=template
src/App.vue?vue&type=script
src/App.vue?vue&type=style

webpack

webpack exposes loaders in the resourceQuery:

module.exports = {
  rules: [{
    test: /\.tsx$/,
    resourceQuery: /layer=app-rsc/,
    use: 'rsc-loader'
  }]
}

Rollup

Rollup plugins receive a custom meta object:

export default {
  transform(code, id) {
    const meta = this.getModuleInfo(id).meta;
    // Contains custom layer info
  }
}

Alternative Approaches

Option 1: Custom SWC Plugin API Extension

Add a layer field to TransformContext:

// In swc_core
pub struct TransformContext {
  pub filename: String,
  pub layer: Option<String>, // NEW: "app-rsc" | "app-client" | "app-ssr"
  pub is_server: bool,
  pub is_dev: bool,
}

Pros: Cleaner API, type-safe
Cons: Requires SWC core changes, not backward-compatible

Option 2: Filename Prefix (not suffix)

[app-rsc]app/page.tsx
[app-client]app/page.tsx

Pros: Less likely to break existing tooling
Cons: Breaks import resolution if not stripped properly

Option 3: Virtual Module Prefix

virtual:app-rsc:app/page.tsx

Pros: Clear that it's not a real file path
Cons: Harder to map back to source files

Recommendation

Use query parameters (proposed solution):

1. ✅ Minimal breaking changes (plugins that don't care about layer ignore the query string)
2. ✅ Precedent in Vite (proven pattern)
3. ✅ Backward compatible (source maps can strip query params)
4. ✅ Easy to parse (standard URLSearchParams API)

Implementation checklist:

• Add query param in next/build/swc/index.ts transform calls
• Update source map generation to strip query params (or keep them for debugging)
• Document in SWC plugin API guide
• Add test cases for coverage tools (Canyon, Istanbul, c8)

Security/Performance Considerations

Performance: ✅ No impact (query params are just strings, no extra I/O)

Security: ✅ No concerns (layer info is already exposed via is_server flag)

Caching: ⚠️ Check if Next.js SWC cache keys on filename → may need to include query params in cache key

Rollout Strategy

Phase 1 (Next.js 16.2):

• Add ?layer=... query param to TransformContext filenames
• Keep existing is_server flag for backward compat
• Document in release notes

Phase 2 (plugin ecosystem):

• Update official plugins (e.g., @next/swc-plugin-coverage)
• Community plugins adapt (Canyon, Sentry, etc.)

Phase 3 (deprecation, Next.js 17):

• Consider removing is_server flag if layer is sufficient

For Plugin Authors

How to detect this change:

// In your SWC plugin
function transform(source, filename, config) {
  const url = new URL(filename, 'file://');
  const layer = url.searchParams.get('layer'); // "app-rsc" | "app-client" | "app-ssr" | null
  
  if (layer === 'app-rsc') {
    // Server-only transforms
  } else if (layer === 'app-client') {
    // Client-only transforms
  }
  
  // Strip query params for source map mapping
  const cleanFilename = filename.split('?')[0];
  // ...
}

---

tl;dr: Next.js compiles files 2-3x for RSC/client/SSR. Adding ?layer=... query params to filenames lets SWC plugins distinguish between passes. This matches Vite's pattern and solves coverage tool issues.

[darshjme-codes]

Triage: SWC - Duplicate transform for "use client" components → performance impact (double compilation)