# Add Server-Side Rendering to a Lit Component

Yes. An agent pre-renders your Lit component with @lit-labs/ssr, hydrates it in the browser, adds a Node render check and opens a PR with the output.

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

## 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\`<my-element name="Server"></my-element>\`` to a string and asserts it contains `<template shadowroot="open"` and `Hello, Server`. A `test:ssr` script runs it after `build`, and `test` chains it before the browser runs, so a change that breaks server rendering fails `npm test` with the string that was produced. `@lit-labs/ssr` asks for Node 20 or newer through its `@types/node` peer, and the agent records the version it ran on in the pull request. The component needs no change: it reads no `window`, and the agent notes that a future component that does should guard it with `isServer` from `lit`.

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`

```json
{
  "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"
    }
  ]
}
```

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 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.

## 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

- [Set Up Storybook for Lit Web Components](https://getrush.ai/run/add-storybook/lit/)
- [Migrate a Lit Component Library to ESLint Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/lit/)
- [Upgrade npm Dependencies Weekly for a Lit Component Library](https://getrush.ai/run/upgrade-npm-dependencies/lit/)

## The same job on other stacks

- [Add Server-Side Rendering to an Angular App](https://getrush.ai/run/add-ssr/angular/)

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

- [Add a Staging Overlay with Kustomize from a Linear Issue](https://getrush.ai/run/add-staging-overlay/kustomize/)
- [Persist Redux Toolkit State Across Page Reloads](https://getrush.ai/run/add-state-persistence/redux-toolkit/)

## 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/)
