# Add a React Wrapper to a Lit Component

Yes. An agent wraps your Lit element with @lit/react's createComponent, types its events, adds a ./react entry point, tests it in a browser and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-react-wrapper/lit/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the component and the build before it writes a wrapper, because the wrapper has to match the element's public surface exactly. In a project started from lit/lit-element-starter-ts, `src/my-element.ts` defines `my-element` with `@customElement`, two reactive properties, `name` as a string and `count` with `type: Number`, a button with `part="button"` that increments `count` and dispatches a `count-changed` `CustomEvent`, and a default slot; a `declare global` block adds the tag to `HTMLElementTagNameMap`. `package.json` names the package `@lit/lit-starter-ts`, version `2.0.3`, with `"type": "module"`, `main` and `module` both pointing at `my-element.js`, `lit` at `^3.2.0` as the only dependency, and `tsc` as the whole build; `tsconfig.json` compiles `src/` into the package root with declarations, `experimentalDecorators` and `"types": ["mocha"]`. Tests live in `src/test/my-element_test.ts`, written with `@open-wc/testing`, and `web-test-runner.config.js` runs the compiled `test/**/*_test.js` in Chromium, Firefox and WebKit through Playwright, in Lit's development and production modes. `.gitignore` ignores the compiled `my-element.js` and `test/`, and `rollup.config.js` bundles `my-element.js` only for the size check and the docs site.

The wrapper comes from `@lit/react`, version 1.0.8 when read, whose README describes `createComponent`: it takes the tag name, the element class, the `react` module and an `events` map from React prop names to DOM event names, sets React props on the element as properties rather than attributes, and attaches listeners for the mapped events; an `EventName` type cast on a map entry gives the callback the right event type. Its peer dependency range for `@types/react` covers 17, 18 and 19. The agent adds `src/react.ts` that imports `React`, `createComponent` and `EventName`, imports `MyElement` from `./my-element.js`, and exports `MyElementReact = createComponent({tagName: 'my-element', elementClass: MyElement, react: React, events: {onCountChanged: 'count-changed' as EventName<CustomEvent>}})`. Because `src/` compiles to the package root, that file becomes `react.js` with a `react.d.ts` beside it, so the agent adds an `exports` map to `package.json` with `"."` for `./my-element.js` and `"./react"` for `./react.js`, keeping `main` and `module` as they are for tools that do not read `exports`, and lists `@lit/react` as a dependency and `react` as a peer dependency so the wrapper never bundles its own copy of React.

The test is written for the runner the project already has rather than a new one. `src/test/react_test.ts` adds `react` and `react-dom` as development dependencies, renders `MyElementReact` into a fixture with `createRoot` from `react-dom/client` inside `act`, passes `name="Lit"` and an `onCountChanged` spy, then clicks the button through the element's shadow root and asserts the heading shows the greeting for `Lit`, that `count` on the underlying element is `1`, and that the spy received a `CustomEvent` of type `count-changed`. The file uses `React.createElement` rather than JSX so `tsconfig.json` needs no `jsx` setting and `lit-analyzer` keeps linting `src/` unchanged. `.gitignore` already ignores `test/`, and the compiled test lands next to the existing one, so `npm test` runs both in all three browsers and both modes.

Before opening the pull request the agent runs the project's own scripts in its sandbox: `npm ci`, `npm run build`, `npm run lint`, which chains `lit-analyzer` and ESLint, and `npm test`, with the Playwright browsers installed, and keeps the output. It runs `npm run checksize` to show the Rollup bundle of `my-element.js` is unchanged, since the wrapper is a separate entry point. A short section goes into the README under Setup: install `@lit/react` and `react`, import `MyElementReact` from `@lit/lit-starter-ts/react`, and pass `onCountChanged` as a prop. The pull request describes each file, quotes the test output per browser, and notes that React 19 can set properties on custom elements itself, so the wrapper's value there is the typed props and the event map rather than property forwarding.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a React wrapper for the Lit component in this repository using @lit/react. Read package.json, tsconfig.json, src/my-element.ts, the existing tests, web-test-runner.config.js, rollup.config.js and .gitignore first. Add src/react.ts that exports a createComponent wrapper for the element, mapping every custom event the element dispatches to a typed React prop with EventName. Add @lit/react as a dependency and react as a peer dependency; add react and react-dom as devDependencies for tests. Add an exports map to package.json with the main entry and a ./react entry, keeping main and module. Write a test in the project's existing test runner that renders the wrapper with react-dom, sets a property through a prop, triggers the element's event and asserts the callback and the element state. Use React.createElement, not JSX. Run npm ci, npm run build, npm run lint, npm test with the Playwright browsers installed, and npm run checksize, and keep the output. Add a README section on using the wrapper. Open a pull request with the commands and their output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `src/react.ts` and `src/test/react_test.ts`, changes `package.json` for the new dependencies and the `exports` map, updates `package-lock.json` and adds a README section. Its description lists the test results per browser and mode as `web-test-runner` printed them, the `lit-analyzer` and ESLint results, and the `checksize` figure for the existing bundle, which the wrapper does not touch. `src/my-element.ts` is unchanged: the wrapper imports the class and reads its properties, so nothing about the element moves to accommodate React.

A reviewer checks whether the package should also publish a `./react` type entry under `typesVersions` for older TypeScript module resolution, whether `react` belongs in `peerDependencies` with the version range their consumers use, and whether an element with more events than this one should map all of them, which the agent does from the `@fires` tags in the element's JSDoc. Pulling the branch and running `npm test` runs the new test alongside the existing one in the same three browsers.

## Run it on every Linear issue labelled react-wrapper

An automation in the Project that holds the component library takes a `linear` trigger on `linear.issue.labeled` with the label `react-wrapper`. Its runs are read-only, so the saved prompt asks for a plan: the run reads the element the issue names, lists its properties and the events in its `@fires` tags, and posts a comment on the issue with the wrapper, the `exports` entry and the test it would add. A handler on the team's server then starts the run that writes the pull request, sending this body with the issue's URL in `resources` and a `request_id` that is a UUID v5 of the issue id, so a retried start returns the run already started.

Each component gets its own run and its own pull request, so a library with several elements gets one reviewable change per element rather than one large one.

## Why run it on Rush?

A wrapper that compiles is not a wrapper that works: whether the property lands on the element and whether the event reaches the callback are only visible in a browser, with React and the custom element loaded together. The agent runs the project's own test runner in its own sandbox, in Chromium, Firefox and WebKit, and keeps the output in the run's record, so the pull request shows the wrapper rendering and the event firing rather than a file that type-checks.

The change follows the project's own conventions, read from its files: `src/` compiling to the package root decides where `react.js` ends up and what the `exports` map must say; the existing `_test.ts` naming and `@open-wc/testing` fixture decide how the new test is written; and `lit-analyzer` and ESLint keep running unchanged. A library with ten elements gets ten runs, each wrapping one element with its own events.

## Frequently asked questions

### Do I need React to build or ship the component?

No. `react` is a peer dependency the consuming app already has, and the Lit element itself does not import it. `react` and `react-dom` are installed as development dependencies only so the test can render the wrapper in a browser.

### Why not just use the custom element directly in React 19?

React 19 sets properties on custom elements and attaches listeners for unknown `on*` props, so the raw element works. The wrapper adds what React cannot infer: a typed prop for each property and a named, typed callback for each custom event, through the `EventName` cast, so a wrong prop name or event type is a compile error.

### Will the wrapper change my bundle size?

Not for the element. `react.js` is a separate entry point that only consumers who import `./react` load, and `rollup.config.js` still bundles `my-element.js` alone. The pull request includes the `checksize` output to show the figure is unchanged.

### What if my element dispatches more than one event?

Each one gets an entry in the `events` map. The agent reads them from the `@fires` tags in the element's JSDoc and from the `dispatchEvent` calls in the source, and names the props `on` plus the event name in camel case, so a `value-changed` event becomes `onValueChanged`.

### Does the test run in CI?

If the repository has a workflow that runs `npm test`, yes, because the compiled test lands in `test/` next to the existing one and `web-test-runner.config.js` picks up every `_test.js` file. The starter has no workflow of its own, and the pull request says so.

## More Lit jobs

- [Add an npm Release Workflow to a Lit Component](https://getrush.ai/run/add-release-workflow/lit/)
- [Add Server-Side Rendering to a Lit Component](https://getrush.ai/run/add-ssr/lit/)
- [Set Up Storybook for Lit Web Components](https://getrush.ai/run/add-storybook/lit/)

## More jobs like this: Turn a Linear label into a PR

- [Add Reading Time to Posts in an Astro Site from a Linear Issue](https://getrush.ai/run/add-reading-time/astro/)
- [Add Reading Time to a Jekyll Blog](https://getrush.ai/run/add-reading-time/jekyll/)
- [Add Redirects for Moved Pages to a Docusaurus Site](https://getrush.ai/run/add-redirects/docusaurus/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
