What the agent does
The agent reads how the component is built, tested and documented, since server rendering touches all three. In a project like lit/lit-element-starter-ts, package.json depends on lit 3 and compiles with tsc from src/ to the package root, so src/my-element.ts becomes my-element.js beside it; tsconfig.json sets experimentalDecorators, module: es2020 and target: es2021. The element itself is a LitElement with a name property, a count property, a render that returns an h1, a button with a count-changed event and a slot, and static styles. Tests run through @web/test-runner with Playwright launchers for Chromium, Firefox and WebKit in both Lit's development and production modes, from test/my-element_test.js. The docs site is Eleventy 1 with .eleventy.cjs as its config, docs-src/ as input and docs/ as output, committed so GitHub Pages serves it; page.11ty.cjs loads my-element.bundled.js, built by Rollup from rollup.config.js, and docs-src/index.md and examples/name-property.md embed <my-element> tags that render only once that bundle runs. The root package.json is type: module, and the Eleventy config is already a .cjs file run with --config=.eleventy.cjs.
Pre-rendering the docs is the first half, and the project's shape fits the official plugin exactly. @lit-labs/eleventy-plugin-lit wants an ESM component module and a CommonJS Eleventy config, which is the layout already here, so the agent adds it with eleventyConfig.addPlugin(litPlugin, { mode: 'worker', componentModules: ['my-element.js'] }) in .eleventy.cjs and an addWatchTarget for the compiled file. From then on every <my-element> in the Markdown is rendered at build time into declarative shadow DOM, a <template shadowroot="open"> holding the heading, the button and the styles, so the examples page shows its content before any script runs. In page.11ty.cjs the agent changes the script loading so hydration support comes first: a small module that imports @lit-labs/ssr-client/lit-element-hydrate-support.js and then the component, which the plugin's README requires to load before Lit itself, bundled by a second Rollup entry so the docs stay a static site, plus the @webcomponents/template-shadowroot polyfill call for browsers without declarative shadow DOM support, placed after the pre-rendered HTML.
The second half is a render check that does not need a browser. The agent adds scripts/ssr-check.js, a Node script that imports render from @lit-labs/ssr, collectResult from its lib/render-result.js, and the compiled my-element.js, renders html\to a string and asserts it contains<template shadowroot="open"andHello, Server. A test:ssrscript runs it afterbuild, and testchains it before the browser runs, so a change that breaks server rendering failsnpm testwith the string that was produced.@lit-labs/ssrasks for Node 20 or newer through its@types/nodepeer, and the agent records the version it ran on in the pull request. The component needs no change: it reads nowindow, and the agent notes that a future component that does should guard it with isServerfromlit`.
Then the whole chain runs in the sandbox: npm install, npm run build, npm run lint, npm test with the three Playwright browsers it downloads, and npm run docs, which cleans, builds, analyzes, bundles and regenerates docs/. The regenerated docs/index.html and docs/examples/name-property/index.html now carry the pre-rendered markup, and the agent opens them in its browser with npm run docs:serve, confirms the counter button still counts after hydration, disables JavaScript and confirms the heading is still there, and keeps both screenshots.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add server-side rendering to this Lit component project. Read package.json, tsconfig.json, src/my-element.ts, src/test/my-element_test.ts, web-test-runner.config.js, rollup.config.js, .eleventy.cjs and docs-src/_includes/page.11ty.cjs first. Add @lit-labs/eleventy-plugin-lit to .eleventy.cjs in worker mode with my-element.js as the component module and a watch target, so the docs site pre-renders every my-element tag as declarative shadow DOM. Change the docs page template to load @lit-labs/ssr-client/lit-element-hydrate-support.js before the component through a second Rollup bundle, and add the @webcomponents/template-shadowroot polyfill after the pre-rendered HTML. Add a Node script that renders the element with @lit-labs/ssr and asserts the output contains the shadow root template and the greeting, wire it as test:ssr into npm test, and note which Node version it ran on. Run npm run build, npm run lint, npm test and npm run docs, open the regenerated docs in the browser with and without JavaScript, and open a pull request with the output and screenshots.",
"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 changes package.json, package-lock.json, .eleventy.cjs, rollup.config.js and docs-src/_includes/page.11ty.cjs, adds scripts/ssr-check.js and the hydration entry, and regenerates the HTML under docs/ with the pre-rendered templates in it. Its description quotes the tsc, lint, test-runner and SSR check output, names the Node version, and shows the examples page with JavaScript off and the counter working with it on, from the run's record.
A reviewer reads the Eleventy plugin options and the script order in the page template, which is the one place where a wrong order shows up as a component that renders twice, then reads scripts/ssr-check.js to see what the server output looks like. The regenerated docs/ files are large diffs that are the point of the change, and npm run docs on their machine reproduces them byte for byte.
Run it on every Linear issue labelled ssr
In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, filtered to the ssr label. When an issue such as "the docs examples are blank until the bundle loads" gets the label, the trigger puts the issue after the prompt, and the run reads which pages and components the issue names before changing the build. Only label changes by a person in your Rush org fire it, and the automation starts at most max_runs_per_hour runs in an hour.
An automation's runs are read-only, so the run that pushes the branch starts from your own server: a handler receiving the automation's comment sends this body to POST /o/{org}/sessions with the issue URL in resources and a request_id that is a UUID v5 of the issue id, so a redelivered event returns the run already started.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Server rendering a web component is a question of order: which module loads first, which polyfill runs after the HTML, which Node version renders, and whether the component touches a browser global it cannot have. The agent reads the project's own build and docs pipeline, fits the Lit Labs plugin to the layout it finds, runs the compile, the lint, the three-browser test suite and the docs build in its own sandbox, and keeps every command, its output and the two screenshots in the run's record.
The Node check is the part that keeps the change honest later. A test that renders the element on the server and reads the string it produced fails the moment someone adds a window reference, and it runs in the same npm test the project already has, so the pull request leaves the project with a guard and not only a feature.
Frequently asked questions
Does the component need to change?
Not this one. It reads no browser globals in its constructor or render, which is what server rendering requires. A component that does should guard that code with isServer from lit or move it to firstUpdated, and the SSR check in npm test is what tells you when that is needed.
What is declarative shadow DOM, and which browsers have it?
It is a <template shadowroot="open"> inside the element that the parser turns into a shadow root without a script. Chromium, Safari and Firefox all support it in current releases; the @webcomponents/template-shadowroot polyfill the pull request adds covers older ones and must run after the pre-rendered HTML has been parsed.
Why does hydration support have to load first?
lit-element-hydrate-support.js patches Lit so an element finds its pre-rendered shadow root and adopts it instead of rendering again. If the component module runs before it, the element renders a second copy, which is the only visible failure mode and why the page template loads the support module first.
Does this make the published package server-rendered?
The package already ships plain ES modules, which @lit-labs/ssr can render in any Node application. The pull request adds the Eleventy plugin for the docs site and the Node check for the package; an application that imports the element does its own rendering with the same render call the check uses.
Why are there so many changed files under docs/?
The docs site is committed as built output so GitHub Pages can serve it, and pre-rendering writes the component's markup into each page. The diff is the feature; npm run docs regenerates the same files from docs-src/.
More Lit jobs
The same job on other stacks
More jobs like this: Turn a Linear label into a PR
- Add a Staging Overlay with Kustomize from a Linear Issue (Kustomize)
- Persist Redux Toolkit State Across Page Reloads (Redux Toolkit)