update docs

Author: mohab-sameh

LEGACY.md

@@ -1,40 +1,32 @@
 # Legacy Codemods
 
-This branch keeps the non-high-priority `react-codemod` transforms as a legacy jscodeshift snapshot under [`codemods/legacy/transforms/`](./codemods/legacy/transforms/).
+The following jscodeshift-based codemods from the original [`react-codemod`](https://github.com/reactjs/react-codemod) project are available under [`codemods/legacy/transforms/`](./codemods/legacy/transforms/).
 
-The legacy snapshot is preserved for source reference, upstream-style tests, and branch preview parity with the structure of `reactjs/react-codemod`.
+These codemods are preserved for compatibility and can be run directly with jscodeshift.
 
-## Legacy Catalog
+## Catalog
 
-- [`create-element-to-jsx`](./codemods/legacy/transforms/create-element-to-jsx.js)
-- [`error-boundaries`](./codemods/legacy/transforms/error-boundaries.js)
-- [`findDOMNode`](./codemods/legacy/transforms/findDOMNode.js)
-- [`manual-bind-to-arrow`](./codemods/legacy/transforms/manual-bind-to-arrow.js)
-- [`pure-component`](./codemods/legacy/transforms/pure-component.js)
-- [`pure-render-mixin`](./codemods/legacy/transforms/pure-render-mixin.js)
-- [`React-DOM-to-react-dom-factories`](./codemods/legacy/transforms/React-DOM-to-react-dom-factories.js)
-- [`ReactNative-View-propTypes`](./codemods/legacy/transforms/ReactNative-View-propTypes.js)
-- [`react-to-react-dom`](./codemods/legacy/transforms/react-to-react-dom.js)
-- [`remove-context-provider`](./codemods/legacy/transforms/remove-context-provider.ts)
-- [`remove-forward-ref`](./codemods/legacy/transforms/remove-forward-ref.ts)
-- [`rename-unsafe-lifecycles`](./codemods/legacy/transforms/rename-unsafe-lifecycles.js)
-- [`sort-comp`](./codemods/legacy/transforms/sort-comp.js)
-- [`update-react-imports`](./codemods/legacy/transforms/update-react-imports.js)
-- [`class`](./codemods/legacy/transforms/class.js)
+- [`create-element-to-jsx`](./codemods/legacy/transforms/create-element-to-jsx.js) — convert `React.createElement` calls to JSX
+- [`error-boundaries`](./codemods/legacy/transforms/error-boundaries.js) — rename `unstable_handleError` to `componentDidCatch`
+- [`findDOMNode`](./codemods/legacy/transforms/findDOMNode.js) — update `getDOMNode()` calls to `React.findDOMNode()`
+- [`manual-bind-to-arrow`](./codemods/legacy/transforms/manual-bind-to-arrow.js) — convert manual function bindings to arrow functions
+- [`pure-component`](./codemods/legacy/transforms/pure-component.js) — convert render-only class components to functional components
+- [`pure-render-mixin`](./codemods/legacy/transforms/pure-render-mixin.js) — remove `PureRenderMixin` and inline `shouldComponentUpdate`
+- [`React-DOM-to-react-dom-factories`](./codemods/legacy/transforms/React-DOM-to-react-dom-factories.js) — convert `React.DOM.div(...)` to `React.createElement('div', ...)`
+- [`ReactNative-View-propTypes`](./codemods/legacy/transforms/ReactNative-View-propTypes.js) — replace `View.propTypes` with `ViewPropTypes`
+- [`react-to-react-dom`](./codemods/legacy/transforms/react-to-react-dom.js) — update code for the `react` / `react-dom` package split
+- [`remove-context-provider`](./codemods/legacy/transforms/remove-context-provider.ts) — convert `Context.Provider` elements to `Context`
+- [`remove-forward-ref`](./codemods/legacy/transforms/remove-forward-ref.ts) — remove usages of `forwardRef`
+- [`rename-unsafe-lifecycles`](./codemods/legacy/transforms/rename-unsafe-lifecycles.js) — add `UNSAFE_` prefix to deprecated lifecycle hooks
+- [`sort-comp`](./codemods/legacy/transforms/sort-comp.js) — enforce React component method ordering
+- [`update-react-imports`](./codemods/legacy/transforms/update-react-imports.js) — remove redundant React imports and convert to named imports
+- [`class`](./codemods/legacy/transforms/class.js) — convert `React.createClass` calls to ES6 classes
 
-## Notes
+## Running
 
-- The 6 promoted JSSG transforms are not duplicated in `codemods/legacy/`.
-- This preview branch does not claim that legacy transforms can be run through Codemod Registry.
-- The legacy snapshot keeps the full upstream-style test corpus in `codemods/legacy/transforms/__tests__`.
-- The preview branch CI runs the compatible legacy subset under the current preview runtime:
-
-```bash
-pnpm run test:legacy
-```
-
-- To run the full legacy snapshot test corpus manually from `codemods/legacy/`:
+From `codemods/legacy/`:
 
 ```bash
+pnpm install
 pnpm test
 ```

PARITY_STATUS.md

@@ -1,28 +1,26 @@
-# Legacy Parity Status
+# Parity Status
 
 Last updated: 2026-04-15
 
 Status meanings:
 
-- `Certified`: replacement-grade rollout confidence. Strict/default package tests are green, public test posture is portable, and there are no known rollout-blocking logic gaps versus the legacy jscodeshift codemod. `Certified` may include intentional safe extensions on legacy-unsupported edge cases, as long as intentional legacy behavior remains unbroken.
-- `Legacy Snapshot`: preserved as upstream jscodeshift source and tests on this branch, but not promoted as part of the active JSSG replacement surface.
+- `Certified`: replacement-grade confidence. Tests are green, public test posture is portable, and there are no known logic gaps versus the original jscodeshift codemod. May include safe extensions on edge cases the original did not handle, as long as original behavior remains unbroken.
+- `Legacy`: available as a jscodeshift codemod under `codemods/legacy/`. Not yet ported to JSSG.
 
-## Active JSSG Surface
+## JSSG Codemods
 
-These are the only codemods promoted as active replacements on this branch.
-
-| Codemod | Legacy Source | Status | Notes |
+| Codemod | Original Source | Status | Notes |
 | --- | --- | --- | --- |
-| `replace-use-form-state` | `replace-use-form-state.ts` | `Certified` | Legacy fixture surface plus added multi-import regression coverage are green. Collection-wide replacement on matching `react-dom` imports fixes a real parity gap, and the broader multi-import handling is treated as an acceptable safe extension where legacy only partially migrated files. |
-| `replace-act-import` | `replace-act-import.ts` | `Certified` | Legacy fixture surface plus added multi-import regression coverage. This closes a real parity gap, and the mixed test-utils partial-removal path is an acceptable safe extension that does not break intentional legacy behavior. |
-| `replace-string-ref` | `replace-string-ref.ts` | `Certified` | Legacy fixture surface plus added namespace/default-export/multi-ref coverage are green, and the direct-superclass guard restores the intended direct-superclass behavior by avoiding the prior mixin false positive. |
-| `replace-reactdom-render` | `replace-reactdom-render.ts` | `Certified` | Legacy fixtures plus added multi-alias regression coverage are green. The extra multi-alias handling is an acceptable safe extension over legacy implementation limits; it preserves intentional legacy behavior while covering additional valid cases. |
-| `react-proptypes-to-prop-types` | `React-PropTypes-to-prop-types.js` | `Certified` | Full legacy fixture surface is green, targeted mixed-import validation is aligned, and no JSSG-specific rollout blocker was found in the audit. No additional extension beyond the legacy behavior is currently relied on for certification. |
-| `use-context-hook` | `use-context-hook.ts` | `Certified` | Legacy fixture surface plus added multi-import regression coverage are green. The multi-import handling goes beyond the legacy implementation, but it is treated as an acceptable safe extension because it preserves intentional legacy behavior while covering additional valid cases. |
+| `replace-use-form-state` | `replace-use-form-state.ts` | `Certified` | Full fixture coverage plus multi-import regression tests are green. Collection-wide replacement on matching `react-dom` imports fixes a real parity gap. |
+| `replace-act-import` | `replace-act-import.ts` | `Certified` | Full fixture coverage plus multi-import regression tests. Mixed test-utils partial-removal path is a safe extension. |
+| `replace-string-ref` | `replace-string-ref.ts` | `Certified` | Full fixture coverage plus namespace/default-export/multi-ref tests are green. Direct-superclass guard restores intended behavior. |
+| `replace-reactdom-render` | `replace-reactdom-render.ts` | `Certified` | Full fixture coverage plus multi-alias regression tests are green. |
+| `react-proptypes-to-prop-types` | `React-PropTypes-to-prop-types.js` | `Certified` | Full original fixture surface is green. No JSSG-specific rollout blocker found. |
+| `use-context-hook` | `use-context-hook.ts` | `Certified` | Full fixture coverage plus multi-import regression tests are green. |
 
-## Legacy Snapshot Surface
+## Legacy Codemods
 
-These codemods remain available only as an upstream jscodeshift snapshot under [`codemods/legacy/transforms/`](./codemods/legacy/transforms/):
+These codemods are available as jscodeshift transforms under [`codemods/legacy/transforms/`](./codemods/legacy/transforms/):
 
 - `class`
 - `create-element-to-jsx`

README.md

@@ -1,25 +1,61 @@
-# React Codemods Preview
+# React Codemods
 
-This branch is a React-facing preview of how this repo should look as a replacement-style home for `react-codemod`.
+This repository contains a collection of codemods to help update React apps.
 
-It promotes 6 audited JSSG codemods as the active surface and preserves the remaining upstream jscodeshift codemods as a legacy snapshot.
+All codemods are free and open source, with the source code available in this repository.
 
-## Active JSSG Transforms
+## Usage
 
-These transforms are the active replacement surface on this branch. They are source-first JSSG codemods and are not described here as Codemod Registry entries unless they are actually published.
+Run a codemod from this directory using the [Codemod CLI](https://go.codemod.com/cli-docs):
 
-- [`use-context-hook`](./codemods/jssg/use-context-hook/) — replace `useContext` usage with `use`
-- [`replace-act-import`](./codemods/jssg/replace-act-import/) — move `act` from `react-dom/test-utils` to `react`
-- [`replace-string-ref`](./codemods/jssg/replace-string-ref/) — replace deprecated string refs with callback refs
-- [`replace-use-form-state`](./codemods/jssg/replace-use-form-state/) — rename `useFormState` to `useActionState`
-- [`replace-reactdom-render`](./codemods/jssg/replace-reactdom-render/) — replace `ReactDOM.render` with `createRoot(...).render(...)`
-- [`react-proptypes-to-prop-types`](./codemods/jssg/react-proptypes-to-prop-types/) — replace `React.PropTypes` with `prop-types`
+```bash
+pnpm dlx codemod@latest jssg run --language tsx --target <path> ./codemods/jssg/<transform>/scripts/codemod.ts
+```
+
+- `<transform>` — name of the codemod (see available codemods below)
+- `<path>` — files or directory to transform
+
+## Available Codemods
+
+### `use-context-hook`
+
+Replaces usages of `React.useContext(...)` with `React.use(...)`.
+
+See [`use-context-hook`](./codemods/jssg/use-context-hook/) for details.
+
+### `replace-act-import`
+
+Updates `act` import path from `react-dom/test-utils` to `react`.
+
+See [`replace-act-import`](./codemods/jssg/replace-act-import/) for details.
+
+### `replace-string-ref`
+
+Replaces deprecated string refs with callback refs.
+
+See [`replace-string-ref`](./codemods/jssg/replace-string-ref/) for details.
+
+### `replace-use-form-state`
+
+Replaces usages of `useFormState()` with `useActionState()`.
 
-## Legacy Codemods
+See [`replace-use-form-state`](./codemods/jssg/replace-use-form-state/) for details.
 
-All non-priority transforms are preserved as an upstream-style legacy jscodeshift snapshot under [`codemods/legacy/`](./codemods/legacy/).
+### `replace-reactdom-render`
 
-See [LEGACY.md](./LEGACY.md) for the legacy catalog and testing notes.
+Replaces usages of `ReactDOM.render()` with `createRoot(node).render()`.
+
+See [`replace-reactdom-render`](./codemods/jssg/replace-reactdom-render/) for details.
+
+### `react-proptypes-to-prop-types`
+
+Replaces `React.PropTypes` references with the `prop-types` package and adds the appropriate import statement.
+
+See [`react-proptypes-to-prop-types`](./codemods/jssg/react-proptypes-to-prop-types/) for details.
+
+### Legacy Codemods
+
+Additional jscodeshift-based codemods from the original `react-codemod` project are available under [`codemods/legacy/`](./codemods/legacy/). See [LEGACY.md](./LEGACY.md) for the full catalog.
 
 ## Development
 
@@ -28,15 +64,28 @@ pnpm install
 pnpm run ci
 ```
 
-Run active JSSG checks only:
+Run tests:
+
+```bash
+pnpm test
+```
+
+Run type checking:
 
 ```bash
-pnpm run test:active
-pnpm run check-types:active
+pnpm run check-types
 ```
 
-Run the legacy snapshot test harness:
+Run legacy codemod tests:
 
 ```bash
 pnpm run test:legacy
 ```
+
+## Support and Contributing
+
+If you want to contribute, you're welcome to submit a pull request.
+
+## License
+
+react-codemod is [MIT licensed](./LICENSE).

package.json

@@ -1,8 +1,8 @@
 {
-  "name": "react-codemod-preview",
+  "name": "react-codemod",
   "version": "0.1.0",
   "private": true,
-  "description": "Preview repo surface for React codemods with active JSSG replacements and a legacy snapshot",
+  "description": "A collection of codemods to help update React apps",
   "type": "module",
   "scripts": {
     "lint": "node ./scripts/validate-docs.mjs",