# Add PWA Support to a Docusaurus Site

Yes. An agent adds @docusaurus/plugin-pwa to your Docusaurus site with a manifest, icons and an offline service worker, builds it, and opens a PR.

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

## What the agent does

The agent starts from how the site is built and served. In a documentation site laid out like react-navigation/react-navigation.github.io, `docusaurus.config.ts` sets `url` to `https://reactnavigation.org`, `baseUrl` to `/`, `favicon` to `img/spiro.svg`, `onBrokenLinks` to `throw`, and `future.v4` and `future.faster` to `true`, so the build runs on `@docusaurus/faster` and Rspack rather than webpack. `package.json` pins `@docusaurus/core` and `@docusaurus/preset-classic` at 3.10.2 under `packageManager` `yarn@4.0.2`, and `.github/actions/setup/action.yml` installs with `yarn install --immutable` on the Node version `.nvmrc` names. There is no `@docusaurus/plugin-pwa` in `yarn.lock`, no `manifest.json` under `static/`, and `static/img/` holds only SVGs and a `favicon.ico`, so the site has nothing a browser could install.

Then it reads what the build already does to its output, because the PWA plugin touches the same phase. The `plugins` array registers eight local plugins from `src/plugins/`, among them `og-image.ts`, which runs in `postBuild`, renders a PNG with `satori` and `@resvg/resvg-js`, and rewrites every `index.html` under `build/` to add the tag. The agent notes the dependency on `@resvg/resvg-js`, since it is the tool it will use to rasterise the icons too. It also reads `versions.json`, which lists eight documentation versions from `1.x` to `8.x` with `lastVersion` set to `7.x`, and `src/css/custom.css`, where `--ifm-color-primary` is an `hsl()` built from `--primary-hue` 256.3, `--primary-saturation` 53.2% and `--primary-lightness` 50.2%.

It adds `@docusaurus/plugin-pwa` at the same 3.10.2 as the preset and registers it last in `plugins` with `pwaHead` entries for `manifest`, `theme-color`, `icon` and `apple-touch-icon`. It writes `static/manifest.json` with the site title and tagline from the config, `start_url` `/`, `display` `standalone`, and the primary colour converted from that `hsl()` to hex as `theme_color`. A short script, `scripts/generate-pwa-icons.ts`, renders `static/img/spiro.svg` to 192 and 512 pixel PNGs under `static/img/pwa/` with the `Resvg` class the site already imports in `og-image.ts`, and the script is added as a `yarn` command beside `fetch-sponsors`. `offlineModeActivationStrategies` stays at the plugin's default of `appInstalled`, `queryString` and `standalone`, so an ordinary visitor downloads nothing extra. Because the plugin precaches every built `.html` by default and the site ships eight versions of 88 pages each, the agent sets `injectManifestConfig.globIgnores` to leave out `docs/1.x` through `docs/6.x`, and says so in the pull request.

In its sandbox it runs `yarn install --immutable`, `yarn typecheck`, `yarn lint`, `yarn test` and `yarn build`, then checks `build/sw.js` and `build/manifest.json` exist and that `build/index.html` carries the four new head tags. Since the site's own `og-image` plugin rewrites every `index.html` in the same `postBuild` phase in which the PWA plugin computes its precache manifest, the agent compares the revision hashes recorded in `build/sw.js` against the final HTML files and reports which of the two ran last. It serves `build/` with `yarn serve`, opens the site in the sandbox browser with `?offlineMode=true`, confirms in the application panel that the worker is registered and the manifest parses, then cuts the network and reloads `/docs/getting-started` to show it still renders.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add PWA support to this Docusaurus site. Read docusaurus.config.ts, package.json, .nvmrc, .github/actions/setup/action.yml, .github/workflows/ci.yml, versions.json, static/, src/css/custom.css and src/plugins/og-image.ts first. Add @docusaurus/plugin-pwa at the same version as @docusaurus/core, register it in plugins with pwaHead entries for the manifest, theme-color, icon and apple-touch-icon, write static/manifest.json from the site's title, tagline and primary colour, and generate 192 and 512 pixel PNG icons from the existing favicon SVG with a script that uses the @resvg/resvg-js dependency the site already has. Keep the default offlineModeActivationStrategies and use injectManifestConfig to leave documentation versions older than the previous one out of the precache. Run the install, typecheck, lint, test and build commands the CI workflow runs, check that build/sw.js and build/manifest.json exist and that the head tags are in build/index.html, compare the precache revisions in sw.js with the final HTML written by the og-image plugin, serve the build and confirm in a browser with ?offlineMode=true that the service worker registers and a docs page loads offline. Open a pull request that lists every file you added, the icon script's command and the offline check, and say which plugin's postBuild ran last. Do not change the deploy workflow or any documentation content.",
  "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 adds the plugin to `package.json` and `yarn.lock`, a plugin entry with `pwaHead` and `injectManifestConfig` in `docusaurus.config.ts`, `static/manifest.json`, two PNG icons under `static/img/pwa/`, the icon script under `scripts/` with its `package.json` command, and nothing else. Its description lists the four head tags as they appear in `build/index.html`, the sizes of `build/sw.js` and the precache list it was built with, and the output of the five CI commands.

It also carries the offline check as a screenshot from the sandbox browser: the application panel showing the registered worker and the parsed manifest, and `/docs/getting-started` rendered with the network cut. The paragraph on `postBuild` ordering states plainly whether the service worker's revisions matched the HTML the OG image plugin wrote, and if they did not, which precache entries will be refetched on first visit.

Before merging, a reviewer checks the `theme_color` against the brand, decides whether the `globIgnores` list should keep more or fewer versions offline, and considers whether to swizzle `@theme/PwaReloadPopup` so the refresh prompt matches the site's own styling.

## Run it on every Docusaurus site that is not installable

A team that runs several Docusaurus sites sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run it already started. Each run reads its own `docusaurus.config.ts`: a site on webpack rather than `future.faster` gets the same plugin, a site whose favicon is already a PNG skips the icon script, and a site with no versioned docs gets no `globIgnores`.

Give the key a `webhook_url` and each run POSTs `run.completed` with its `session_url` when the turn finishes, or `run.failed` for a site whose build broke, for instance one where `onBrokenLinks: 'throw'` rejects a manifest path. A key runs at most `max_concurrent` runs at once, 4 by default, and any run past that is created with `status: "queued"` and starts as a slot frees, so the loop over repositories needs no retry logic.

## Why run it on Rush?

A PWA is a build-time change whose only proof is a served build in a browser: the worker registers or it does not, the manifest parses or it does not, and the page loads offline or it does not. The agent's sandbox has the Node version `.nvmrc` names, Yarn 4 through corepack and a browser, so it runs the same `yarn build` the Pages workflow runs and shows the result rather than describing it.

The decisions that matter here come from the repository, not from a plugin tutorial: the precache would otherwise swallow eight versions of the docs, the site already has a `postBuild` plugin that rewrites HTML, and the icon can be rendered with a dependency the site already pays for. The build output, the revision comparison and the screenshots stay with the run, so the review reads evidence.

## Frequently asked questions

### Does the plugin work with Docusaurus Faster and Rspack?

Yes. The plugin's `configureWebpack` takes the `currentBundler` Docusaurus passes it and registers its environment plugin through that bundler's instance, and its `postBuild` compiles `sw.js` with the same bundler. The agent builds with `future.faster` left on and confirms `build/sw.js` is produced.

### Will every visitor start downloading the whole site?

No. With the default `offlineModeActivationStrategies`, precaching only runs for visitors who installed the site as an app, who open it in standalone mode, or who add `offlineMode=true` to the query string. The agent keeps those defaults and uses the query string form for its own check.

### What about the og-image plugin?

It rewrites every built `index.html` in `postBuild`, the phase in which the PWA plugin computes the hashes of the files it precaches. The agent compares the revisions in `build/sw.js` with the final files and reports the result; a mismatch means the first offline visit refetches those pages once, and the pull request names the fix if one is needed.

### Does it change the deploy workflow?

No. `.github/workflows/main.yml` already runs `yarn build` and uploads `build/` to GitHub Pages, so `sw.js`, `manifest.json` and the icons ship with the next deploy. The stale `netlify.toml`, which still names Node 12.13, is left alone and mentioned in the description.

### Why generate icons with a script instead of committing PNGs?

The site already depends on `@resvg/resvg-js` for its share image, so rendering `static/img/spiro.svg` at two sizes is a few lines and stays reproducible when the logo changes. The PNGs are committed too, since the build reads them from `static/`.

## More Docusaurus jobs

- [Add Redirects for Moved Pages to a Docusaurus Site](https://getrush.ai/run/add-redirects/docusaurus/)
- [Add a Typo Check to a Docusaurus Site in CI](https://getrush.ai/run/add-typo-check/docusaurus/)
- [Add Versioned Docs to a Docusaurus Site](https://getrush.ai/run/add-versioned-docs/docusaurus/)

## The same job on other stacks

- [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/)
- [Add PWA Support to a React Router v7 App](https://getrush.ai/run/add-pwa-support/react-router/)

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