# 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 Rush](https://cloud.getrush.ai/run/add-pwa-support/astro/). 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 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`

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

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

- [Add Reading Time to Posts in an Astro Site from a Linear Issue](https://getrush.ai/run/add-reading-time/astro/)
- [Add Related Posts to an Astro Blog](https://getrush.ai/run/add-related-posts/astro/)
- [Add a Sitemap to an Astro Blog](https://getrush.ai/run/add-sitemap/astro/)

## The same job on other stacks

- [Add PWA Support to a Docusaurus Site](https://getrush.ai/run/add-pwa-support/docusaurus/)
- [Add PWA Support to a Gatsby Blog](https://getrush.ai/run/add-pwa-support/gatsby/)
- [Add PWA Support to a Nuxt App](https://getrush.ai/run/add-pwa-support/nuxt/)

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