All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading