Proposal for Improving JSX Transform

[magic-akari]

Related Issues:

• React = require("react") is not consistently transpiled inside function  #8786
• jsx classic does not use provided identifier when identifier is via a parameter #10553

---

Observed Behavior in Ecosystem

Current JSX transform implementations (Babel, esbuild, TypeScript) exhibit distinct behaviors regarding scoped @jsx pragma resolution that SWC does not fully replicate. This proposal addresses inconsistencies in local JSX pragma handling.

1. Pragma resolution adheres to lexical scoping
   The jsxPragma always references the nearest available declaration within scope. Example:

   /* @jsx h */
   import h from "preact/jsx-runtime";
   
   const a = <div />; // Resolves to top-level `h`
   
   function b(h) {
       return <div />; // Resolves to locally scoped `h` parameter
   }

   This behavior is consistent across Babel, esbuild, and TypeScript.

2. Nested pragma comments are permitted
   /* @jsx */ directives function in non-top-level scopes:

   /* @jsx h */
   import h from "preact/jsx-runtime";
   
   const a = <div />; // Uses `h`
   
   function b(f) {
       /* @jsx f */
       return <div />; // Uses `f` (supported in Babel/esbuild)
   }

   Post-JSX pragmas in the same scope are honored (Babel/esbuild only):

   function b(f) {
       return <div />;
       /* @jsx f */ // Affects preceding JSX (Babel/esbuild)
   }

   TypeScript limitation: Only processes top-level pragmas

---

Current SWC Behavior

SWC's JSX transform consistently resolves jsxPragma to top-level declarations, disregarding scoping rules. Example:

/* @jsx h */
function b(h) { // SWC renames `h` to `h1` due to conflict
    return <div />; // Incorrectly references top-level `h`
}

Transforms to:

function b(h#2) {
  return h#1("div", null);  // Top-level reference persists
}

---

Proposed Enhancement

Classic JSX transform (non-Automatic) should operate context-independently via jsxPragma directives. Implementation strategies:

Option 1: Early JSX Transformation

flowchart TD
    Parse --> Jsx[JSX transform]
    Jsx --> Resolve
    Resolve --> TS[TS transform]
    TS --> Plugin
    Plugin --> O[Other transforms]
    O --> Rename
    Rename --> Codegen

Loading

Tradeoffs:
Constitutes a breaking change: plugins receive transformed JSX AST, eliminating custom JSX handling. Mitigation approaches:

1. Introduce preserveJsx option for plugin-managed JSX
2. Relocate plugin pass pre-JSX transform (requires TS AST handling)

Option 2: Implement Hygiene + Dual Resolve Passes

flowchart TD
  Parse --> Resolve1[Resolve]
  Resolve1 --> TS[TS Transform]
  TS --> Plugin
  Plugin --> Hygiene
  Hygiene --> Jsx[JSX Transform]
  Jsx --> Resolve2[Resolve]
  Resolve2 --> Other[Other Transforms]
  Other --> Rename
  Rename --> Codegen

Loading

Tradeoff:
Performance impact from dual resolution passes.

---

Note

Applies exclusively to Classic JSX (jsxPragma-based). Automatic JSX (using jsx/jsxs runtime) does not respect /* @jsx */ pragma comments and always utilizes injected runtime pragmas.

[kdy1]

Can we support JSX pragma from the resolver pass? Asking because passing JSX is kind of must for Wasm plugins.

[magic-akari]

I’m a bit worried by the performance regression of the second one, but not sure how much it will be. But I think the second option would be better, and I think we can optimize it from a separate dev branch. Thoguths?

Do you mean Dual Resolve Passes?
I have to admit I don't recommend this option. If we can't move the classic JSX transform earlier in the pipeline, I'd likely implement a patch solution to address the reference issues. However, as previously noted, the problem with TypeScript import stripping would still persist.

[magic-akari]

The patch solution would involve gathering declarations of identifiers while also collecting information from comments. Then, during JSX generation, we'd perform lookup operations against this collected data. Some of these steps overlap with resolver logic, particularly regarding scope management.

[kdy1]

I prefer moving the classic JSX transform to earlier stage. If you are also fine with it I think we can go with it.
The problem is config, but I think we should do SWC v2 soon anyway. (Without stabilizing Wasm plugins as it's not backward compatible)

[kdy1]

I added https://github.com/swc-project/swc/milestone/586 for SWC v2

[magic-akari]

I'll give it a try.

[magic-akari]

I've noticed that the react-refresh module executes before the JSX transform step.
I'm wondering if it's possible to move it after the JSX transformation in the build process.

[kdy1]

We may add some mark to indicate jsx calls as “transformed from JSX” and handle them from fast refresh pass.
Not sure if this is a good idea, though.