All jobs

Add PWA Support to an Astro Site

Yes. An agent adds a web manifest, icons and a service worker to your Astro site with the Vite PWA integration, checks it offline in a browser, and opens a PR.

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 how the site is built before adding an integration. In a blog like satnaing/astro-paper, astro.config.ts sets site from astro-paper.config.ts, registers @astrojs/mdx and @astrojs/sitemap, loads Tailwind through @tailwindcss/vite, declares a Google font and an env schema with one public variable. package.json pins astro ^7.0.3, already depends on sharp ^0.35.2 for the dynamic Open Graph images, requires Node >=22.12.0, and has a build script that runs astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/, so the search index is written after the build and copied back into public/. The lockfile is pnpm's, and pnpm-workspace.yaml allows build scripts for esbuild and sharp only.

It then reads the shell every page shares. src/layouts/Layout.astro links favicon.svg and favicon.ico, writes canonical, Open Graph and RSS tags, has an empty <meta name="theme-color"> that src/scripts/theme.ts fills at runtime to match the light or dark background, and exposes a <slot name="head" /> for child layouts. public/ holds only default-og.jpg and favicon.svg; there is no manifest, no PNG icon and no service worker. astro-paper.config.ts carries the site title, description, language and text direction, and src/styles/theme.css defines the background colours for both themes. .github/workflows/ci.yml runs pnpm run lint, pnpm run format:check and pnpm run build on Node 24 with pnpm 11.3.0.

The agent adds @vite-pwa/astro with pnpm add and registers it in astro.config.ts with registerType: "autoUpdate" and a manifest built from the values already in astro-paper.config.ts: name and short_name from the title, description, lang and dir, start_url and scope at the site root, display: "standalone", and theme_color and background_color taken from the light theme in theme.css, because a manifest holds one static colour. It renders favicon.svg to 192 and 512 pixel PNGs plus a maskable variant with the sharp the project already has, in a small script under scripts/, and lists them in the manifest. The Workbox globPatterns cover the built HTML, CSS, JavaScript, fonts and SVG, with runtime caching for post pages set network-first and /pagefind/ left to the network, since the index fragments are many and change every build. In Layout.astro it adds the manifest link from virtual:pwa-info beside the favicon links and a small src/pwa.ts that calls registerSW so the browser registers sw.js.

Before pushing, the agent runs pnpm install --frozen-lockfile, then pnpm run lint, pnpm run format:check and pnpm run build, the three commands ci.yml runs, and confirms dist/manifest.webmanifest and dist/sw.js exist with the icons beside them. It starts astro preview and opens the site in the sandbox browser, checks the manifest link, registration and installability in the browser's application view, loads the home page and one post, switches the browser offline and reloads both, and keeps screenshots of the results. Then it opens the pull request with those outputs.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add PWA support to this Astro site and open a pull request. Read astro.config.ts, astro-paper.config.ts, package.json, pnpm-workspace.yaml, src/layouts/Layout.astro, src/scripts/theme.ts, src/styles/theme.css, the contents of public/ and .github/workflows/ci.yml first. Add @vite-pwa/astro with pnpm and configure it in astro.config.ts with registerType autoUpdate and a manifest whose name, description, lang, dir, theme_color and background_color come from the values the site already defines; generate 192, 512 and maskable PNG icons from public/favicon.svg with the sharp dependency the project has, in a script under scripts/. Precache the built HTML, CSS, JavaScript, fonts and SVG, cache post pages network-first, and leave /pagefind/ to the network. Add the manifest link to Layout.astro and register the service worker. Run pnpm run lint, pnpm run format:check and pnpm run build, start astro preview, open the site in the browser, confirm the manifest and service worker register and that the home page and one post load offline, and keep screenshots. Describe all of it in the pull request.",
  "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 that changes package.json and pnpm-lock.yaml to add @vite-pwa/astro, astro.config.ts to register it with the manifest and Workbox settings, src/layouts/Layout.astro to link the manifest and load the registration script, and adds src/pwa.ts, scripts/generate-pwa-icons.mjs and the generated PNG icons under public/. The description lists the manifest values and where each came from, the cache rules by file type, and the one choice a reviewer may want to change: the static theme_color, since the site switches themes at runtime.

The proof is the output of the three CI commands run in the sandbox, the listing of dist/manifest.webmanifest, dist/sw.js and the icons, and the browser screenshots of the application view and of the home page and a post loading offline, all kept in the run's record and linked from the description. The repository's own ci.yml runs on the pull request as well.

Before merging, a reviewer checks that the manifest name and colours are what they want on a phone's home screen, that autoUpdate suits a blog that deploys often, that the /pagefind/ exclusion keeps search working after a deploy, and that the icons look right at the maskable crop. Then they deploy a preview and install the site from a phone's browser menu.

Run it on every new Astro repository

A team that starts sites from an Astro template sends this request once per new repository from the terminal or a script: POST /o/{org}/sessions with this prompt and the repository URL in resources, one call each. GET /o/{org}/github lists every repository the Rush GitHub App installation can reach, so a script can find the ones with no manifest.webmanifest in public/ or dist/ and start a run for each. Each run reads that site's own config and layout and opens its own pull request.

Set a webhook URL on the API key and Rush POSTs run.completed or run.failed when a run's turn finishes, with session_url so your server can read the pull request link. Send a fresh UUID as request_id with each request so a retry returns the run already started.

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

Why run it on Rush?

Adding a service worker to a static site is easy to get almost right: the manifest validates, the worker registers, and the site then serves a stale index page for a day because the cache rule caught the wrong route, or search breaks because the index fragments were precached from an older build. On Rush the agent builds the site in its own sandbox, serves it, opens it in a real browser, goes offline and reloads, so the pull request carries screenshots of the behaviour rather than a description of the config. Your machine installs nothing.

Every command, the built file listing and the screenshots stay in the run's record, the diff is small enough to read in one sitting, and nothing deploys until a person merges. The same request can add PWA support to every Astro site the team keeps, each run reading its own config, one pull request each.

Frequently asked questions

Will it cache the search index or the OG images?

No. /pagefind/ is left to the network because the fragments are rebuilt on every deploy and would go stale in a precache, and the dynamic og.png routes are not matched by the glob patterns. Posts are cached network-first, so a reader sees the latest version when online and the last-seen version offline.

Why is theme_color static when the site has two themes?

A web manifest holds one theme_color, so the agent takes the light background from src/styles/theme.css and says so in the pull request. The <meta name="theme-color"> tag that theme.ts fills at runtime keeps switching the browser chrome colour for an open tab; only the installed app's splash and title bar use the manifest value.

Does the service worker run in astro dev?

Not by default. The integration registers the worker in the built output only, so pnpm dev keeps hot reloading without a cache in the way. The agent checks the behaviour against astro preview, which serves dist/ the way a host would.

What about the icons?

The agent renders public/favicon.svg to 192 and 512 pixel PNGs and a maskable 512 with padding, using the sharp package already in dependencies, and commits the script so you can regenerate them after changing the logo. If you prefer hand-made icons, drop them in public/ under the same names.

More Astro jobs

The same job on other stacks

Keep reading