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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
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.