# Add PWA Support to a React Router v7 App

Yes. An agent adds a manifest, icons and a service worker to a server-rendered React Router v7 app, checks it installs and loads offline, and opens a pull request.

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

## What the agent does

The agent reads the app before it adds anything. In an app started from the `default` template in remix-run/react-router-templates, `package.json` has `react-router build`, `react-router dev`, `react-router-serve ./build/server/index.js` and a `typecheck` script that runs `react-router typegen && tsc`; it depends on `react-router`, `@react-router/node` and `@react-router/serve`, `react` and `react-dom` on 19, and `isbot`, with `@react-router/dev`, Vite 8, Tailwind 4 and TypeScript 5.9 for development. `react-router.config.ts` sets `ssr: true`, so every route is rendered on the server and hydrated in the browser. `vite.config.ts` registers only the Tailwind and React Router plugins. `public/` holds a single `favicon.ico`; there is no manifest, no PNG icon and no service worker.

`app/root.tsx` is where the document is built: a `Layout` that renders `<Meta />` and `<Links />` in the head and `<ScrollRestoration />` and `<Scripts />` in the body, a `links` export that preconnects to Google Fonts and loads Inter, and an `ErrorBoundary` that shows a 404 or a stack. `app/routes.ts` registers one index route, `app/routes/home.tsx`, whose `meta` export sets the title to "New React Router App" and a description, and which renders `app/welcome/welcome.tsx` with `logo-light.svg` and `logo-dark.svg`. The repository's own checks live in `.tests/test.default.ts`: a Playwright run that typechecks, starts `pnpm dev` and `pnpm build` then `pnpm start`, loads the page, and asserts that nothing was written to stderr and that the page raised no errors. A change that logs a warning fails that test.

The agent adds the pieces without a plugin, because a hand-written worker is a few dozen lines and avoids a build-time integration with the React Router plugin's server bundle. `public/manifest.webmanifest` names the app, sets `start_url` and `scope` to `/`, `display` to `standalone`, a `theme_color` and `background_color` matching the Tailwind palette in `app/app.css`, and lists `icon-192.png` and `icon-512.png`, which the agent renders from `logo-light.svg` with an image tool in its sandbox and commits under `public/`, including a maskable variant. `root.tsx` gains a `manifest` entry in `links`, an `apple-touch-icon` link, and a `theme-color` meta tag in `Layout`. `public/sw.js` precaches nothing at install, because the built asset names are hashed and unknown to a static file; instead it serves `/assets/` requests cache-first and stores them as they arrive, serves navigations network-first and falls back to the cached document for the same path when the network fails, and drops old caches on activate by version. A small `app/pwa.ts` registers the worker from `useEffect` in `root.tsx` only when `navigator.serviceWorker` exists, so server rendering and the Playwright run are untouched.

The checks are the ones the repository already runs plus the one a PWA needs. The agent runs `pnpm typecheck`, `pnpm build` and `pnpm start`, opens the app in its browser, confirms in the application panel that the manifest parses and the worker is active, loads the page a second time so the assets are cached, sets the browser offline, reloads and sees the page render from the cache, and sets it online again. It runs the repository's Playwright test for the `default` template from `.tests` to show stderr stayed empty, and pastes the manifest, the offline reload result and the test output in the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Make this React Router v7 app a progressive web app and open a pull request. Read package.json, vite.config.ts, react-router.config.ts, tsconfig.json, app/root.tsx, app/routes.ts, app/routes/home.tsx, app/welcome/welcome.tsx, app/app.css, the files under public, Dockerfile, README.md and, at the repository root, .tests/test.default.ts, .tests/utils.ts and .github/workflows/ci.yml first. Add public/manifest.webmanifest with the app name, start_url and scope /, standalone display, theme and background colours matching app.css, and 192 and 512 pixel PNG icons rendered from app/welcome/logo-light.svg including a maskable one. Add the manifest link, an apple-touch-icon link and a theme-color meta tag to app/root.tsx. Add public/sw.js without a plugin: cache-first for /assets/ with runtime caching, network-first for navigations with a cached fallback for the same path, and versioned cache cleanup on activate. Register it from a small app/pwa.ts called in a useEffect in root.tsx only when navigator.serviceWorker exists, so server rendering is unchanged. Run pnpm typecheck, pnpm build and pnpm start, confirm in the browser that the manifest and worker are active and that the page reloads while offline, run the default template's Playwright test from .tests and confirm stderr is empty, and paste the results in the pull request. Add a PWA note to README.md. Do not add a dependency and do not change the Dockerfile.",
  "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

What comes back is a pull request on its own branch. It adds `public/manifest.webmanifest`, `public/icon-192.png`, `public/icon-512.png`, a maskable icon, `public/sw.js` and `app/pwa.ts`, changes `app/root.tsx` and `README.md`, and leaves `package.json`, `vite.config.ts` and the `Dockerfile` untouched, which the file list shows. The description pastes the manifest, states what the worker caches and what it does not, and shows the offline reload and the Playwright output from the sandbox.

The run's full record at `GET /o/{org}/sessions/{id}/messages` keeps the typecheck, build and start output, the browser steps with the application panel and the offline reload, and the `.tests` run. `GET /o/{org}/p/{project}/sessions/{id}/changes` returns each file's diff, and the icons are listed as binary additions.

Before merging, a reviewer checks that the worker never caches the server-rendered document for a path other than the one requested, that `/assets/` is the only cache-first prefix so API routes added later are not served stale, that the registration runs only in the browser, and that the cache version string is bumped in the same change whenever `sw.js` changes. Nothing is deployed.

## Run it on every new frontend release

A team with several React Router apps starts one run per repository from the terminal with `POST /o/{org}/sessions`, this prompt and the repository in `resources`. Each run reads that app's own routes and config, so an app with `ssr: false` gets a worker that precaches the single `index.html`, an app with API routes gets those paths excluded from caching, and an app that already links a manifest keeps it. Each run ends in its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with `session_url` to read the pull request from. A `request_id` per repository returns the run already started when the batch is sent twice.

## Why run it on Rush?

A PWA on a server-rendered app is mostly a set of small things that only show up in a browser: a manifest that fails to parse, an icon without the purpose the installer wants, a worker that caches the wrong document and serves one route's HTML for another. The agent has a browser in its sandbox, so it installs the app, goes offline and reloads before it pushes, and the repository's own Playwright test runs beside it.

The pull request carries the manifest, the caching rules in plain words and the offline result, and the trajectory keeps every command and browser step, so a reviewer can judge the change from the record rather than from a laptop install.

## Frequently asked questions

### Why not vite-plugin-pwa?

It is a good choice for a client-rendered Vite app, where the plugin can precache the built index and assets. Here the document is rendered by the server bundle that `@react-router/dev` produces, and a hand-written worker with runtime caching of `/assets/` and network-first navigations does the job with no new dependency and nothing to configure against the plugin's server build. Say so in the prompt if you prefer the plugin and the agent wires it up with the manifest and a `virtual:pwa-register` call instead.

### What works offline?

Pages the user has already visited, served from the cached server-rendered document and the hashed assets stored on first load. A route never visited is not cached and shows the browser's offline page. The pull request says this plainly so nobody expects a full offline app from a worker that precaches nothing.

### Will the service worker break the Playwright test?

No. Registration happens in a `useEffect` after hydration, only when `navigator.serviceWorker` exists, and logs nothing on success. The test asserts that stderr is empty and the page raised no errors, and the agent runs it in the sandbox to show both still hold.

### How do updates reach users?

A new build changes the asset hashes and the agent bumps the cache version in `sw.js` in the same change, so the next load installs the new worker, drops the old caches on activate and fetches fresh documents network-first. The worker calls `skipWaiting` and `clients.claim` so the new version takes over without a second reload.

## More React Router jobs

- [Add Rate Limiting to a React Router App](https://getrush.ai/run/add-rate-limiting/react-router/)
- [Add Request ID Logging to a React Router App](https://getrush.ai/run/add-request-id-logging/react-router/)
- [Add Security Headers and a CSP to a React Router App](https://getrush.ai/run/add-security-headers/react-router/)

## The same job on other stacks

- [Add PWA Support to a SolidJS App](https://getrush.ai/run/add-pwa-support/solidjs/)
- [Add PWA Support to a SvelteKit App](https://getrush.ai/run/add-pwa-support/sveltekit/)
- [Add PWA Support to a Vite React App](https://getrush.ai/run/add-pwa-support/vite-react/)

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