jsx-new-transform
Migrate React default/namespace imports for the new JSX transform (jscodeshift tutorial parity)
# jsx-new-transform
**Rewrites `import React` / `import * as React` to named or namespace imports so code matches the [automatic JSX runtime](https://react.dev/blog/2020/09/22/introducing-the-new-jsx-transform) (same goal as the Backstage [JSX migration tutorial](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/jsx-migration-codemod.md), not Backstage-specific).
## What it does
- Finds value imports from `react` where the binding is `React` (default or `import * as React`).
- **Safe destructure path:** When `React` is only used as a qualifier (`React.createElement`, `React.FC`, `<React.Fragment>`, etc.) and there are no conflicting bindings, replaces those uses and switches to **named** / **`import type`** imports from `react`.
- **Fallback:** When `React` is still needed as a value (e.g. returned or passed around), rewrites toward **`import * as React from "react"`** (including splitting default + named imports when needed).
- **Cleanup:** Removes unused default or namespace `React` imports when nothing references `React`.
- **Errors:** Throws if more than one conflicting `React` binding import is found (same rule as the original jscodeshift recipe).
## Metrics
| Metric | Meaning |
|--------|---------|
| **`jsx-react-import-outcome`** | One row per file outcome. Dimension **`outcome`**: `destructured`, `namespace-fallback`, `namespace-fallback-split`, `removed-unused-namespace`, `removed-unused-default`, `skipped-no-react-import`, `error-duplicate-react-import`, `unchanged`. |
| **`jsx-react-destructure-symbols`** | When destructuring, counts symbols pulled into imports. Dimensions **`symbol`** (`imported:local`), **`kind`**: `value` or `type`. |
| **`jsx-react-member-replaced`** | Counts qualifier rewrites. Dimension **`kind`**: `nested_type_identifier` (e.g. `React.FC` → `FC`) or `member_expression` (e.g. `React.memo` → `memo`, JSX `React.Fragment` → `Fragment`). |
## Workflow parameters
- **`destructureNamespaceImports`** (boolean, default `true`): When `true`, also attempt to destructure `import * as React` when only `React.*` access is used (aligned with the tutorial’s `--destructureNamespaceImports=true`).
**Workflow** (see `workflow.yaml`): runs the JSSG step on `**/*.{ts,tsx,js,jsx}` excluding `node_modules`.