All jobs

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

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

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

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

The same job on other stacks

Keep reading