[Question] Plugin-injected imports renamed by hygiene pass - how to preserve identifier names?

[pedrofcarvalho]

Establishing Context

I am migrating our internal build tool from Babel to SWC, and internally, we have our own UI framework, and we need to support both our renderers for React and the internal framework.

Practically speaking, I need some arbitrary Pragma to be called for the JSX transformation and add an import statement like so:
import { createElement as jsxPragma_createElement } from "either-react-or-internal-renderer";

Currently, I am adding this import statement with a custom Rust-based SWC plugin. Now let me explain what is my problem below.
Note: Having 2 frameworks is not part of the question, the final goal is to add support for both.

Problem Statement

My SWC plugin injects the JSX pragma imports, but the hygiene pass automatically renames the imported identifiers by adding numeric suffixes (e.g., jsxPragma_createElement → jsxPragma_createElement1).

This breaks the JSX transformation, since the pragma configuration expects the original identifier name.

Broken transformation example

Original source code:

import styles from './styles.scss';

const componentView = () => (
	<div>
		<h1>Nani</h1>
	</div>
);

Expected transformed code:

import { createElement as jsxPragma_createElement } from "my-renderer-library";
import styles from './styles.scss';
const componentView = ()=>{
    return /*#__PURE__*/ jsxPragma_createElement("div", null, /*#__PURE__*/ jsxPragma_createElement("h1", null, "Nani"));
};

Actual transformed code:

import { createElement as jsxPragma_createElement1 } from "my-renderer-library";
import styles from './styles.scss';
const componentView = ()=>{
    return /*#__PURE__*/ jsxPragma_createElement("div", null, /*#__PURE__*/ jsxPragma_createElement("h1", null, "Nani"));
};

Current Setup

SWC Config:

{
  jsc: {
    parser: {
      syntax: hasTS ? "typescript" : "ecmascript",
      ...(hasTS ? { tsx: true } : { jsx: true }),
      externalHelpers: true,
    },
    transform: {
      react: {
        runtime: "classic",
        pragma: "jsxPragma_createElement",
        pragmaFrag: "jsxPragma_Fragment",
      },
    },
    experimental: {
      plugins: [["my-jsx-plugin", { /* config */ }]],
    },
    module: {
      type: "es6"
    }
  },
}

Final Question

Is there any known way to go around this problem?
Am I doing this the wrong way?

I'm new to compilers, Babel and SWC, so I'm learning along the way.
I would love some pointers from the community, thank yall so much in advance!!!

[kdy1]

If you want to override how JSX classic runtime works, you need top_level_mark.

https://swc.rs/docs/contributing/es-commons/variable-management#syntax-context

But not sure if the top-level mark is passed to the Wasm plugin.

[pedrofcarvalho]

@kdy1, I wanted to update this thread on my custom JSX transform plugin and ask a (hopefully) final question:
The JSX transformation I implemented worked for my original purpose, but I am running into a bit of a strange wall now.

Context
Currently, the plugin adds an import for the createElement function need a pragma to be added to ensure there will be no duplicates (we don't have the option to be opinionated and force users to not use that function name 😞).

Here is what it looks like currently:

import { createElement as jsxPragma_createElement } from "@servicenow/ui-renderer-snabbdom";

The New Problem
For any functional component (either import or locally defined), it seems that the SWC hygiene pass is renaming the functional component definitions, even though I'm not touching them. The only thing that changes in their line is that the plugin is adding the jsxPragma_createElement call to define that function.

Broken transformation examples

Source code (before transformation):

import { createElement as jsxPragma_createElement } from "@servicenow/ui-renderer-snabbdom";
const LoadingState = () => (
  <div className="counter-container">
    <div className="counter-loading">
      // something in here...
    </div>
  </div>
);
    
export const defineComponentView = (dataLoaded)=>{
  if (!dataLoaded) {
    return <LoadingState />;
  }

  // rest of view...
};

Broken transformed code (after transformation):

import { createElement as jsxPragma_createElement } from "@servicenow/ui-renderer-snabbdom";
const LoadingState1 = () => jsxPragma_createElement("div", {
    // ...
})));
    
export const defineComponentView = (dataLoaded)=>{
    if (!dataLoaded) {
        return jsxPragma_createElement(LoadingState, null);
    }
    // rest of view...
};

---

What am I missing here?

• Am I making some incorrect assumption here?
• Is this expected behavior?

Thanks in advance!

[kdy1]

I think something is wrong. After all, why is JSX left after your transform? I think I misunderstood something

[pedrofcarvalho]

Hmmm, what do you mean?
There is no JSX left in the transformed code.

This is the code after transformation:

import { createElement as jsxPragma_createElement } from "@servicenow/ui-renderer-snabbdom";
const LoadingState1 = () => jsxPragma_createElement("div", {
    // ...
})));
    
export const defineComponentView = (dataLoaded)=>{
    if (!dataLoaded) {
        return jsxPragma_createElement(LoadingState, null);
    }
    // rest of view...
};

The issue here is that LoadingState was renamed to LoadingState1 for some reason

[kdy1]

It's because you used wrong SyntaxContext for LoadingState.
Doc: https://swc.rs/docs/contributing/es-commons/variable-management

[pedrofcarvalho]

@kdy1 What do you recommend adding to my SyntaxContext?
I thought that adding SyntaxContext::empty().apply_mark(self.unresolved_mark) to the Ident constructor would fix my issue, but it didn't.

This is my current implementation when inserting the pragma call:

// Construct the final call expression: pragma(type, props, ...children)
Expr::Call(CallExpr {
    span: DUMMY_SP,
    ctxt: SyntaxContext::empty(),
    callee: Callee::Expr(Box::new(pragma_identifier)),
    args: call_arguments,
    type_args: None,
})

Full function located on my Gist

[sunnypatell]

@pedrofcarvalho the hygiene pass renames your injected identifiers because they get a fresh SyntaxContext that doesn't match anything else in the AST. the fix is to use unresolved_mark from the plugin's program metadata for your injected identifiers.

// in your plugin
fn visit_mut_module(&mut self, module: &mut Module) {
    let ctxt = SyntaxContext::empty().apply_mark(self.unresolved_mark);

    // use this ctxt for BOTH the import binding and JSX references
    let pragma = Ident::new("jsxPragma_createElement".into(), DUMMY_SP, ctxt);

    // inject: import { createElement as jsxPragma_createElement } from "..."
    // and reference `pragma` everywhere in JSX
}

the key insight: unresolved_mark tells the hygiene pass "this is an external/top-level binding, don't rename it." since both your import specifier and your JSX references share the same mark, the hygiene pass treats them as the same binding and leaves them alone.

without this, your import gets one context and your usage gets another, so the hygiene pass thinks they're different identifiers and renames one of them.

ref: SWC plugin cheatsheet covers how marks work in the transform pipeline.