# Add Analytics to an Astro Blog

Yes. An agent adds a privacy-friendly analytics script to your Astro site behind a config option, checks it counts view-transition navigations, and opens a PR.

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

## What the agent does

The agent clones the site into its own cloud sandbox and reads how the theme is configured before it adds a tag anywhere. In an Astro blog like satnaing/astro-paper, `package.json` pins `astro` `^7.0.3`, uses pnpm with a `pnpm-lock.yaml`, requires Node 22.12 or newer, and has no test script: `build` runs `astro check && astro build`, then indexes the output with `pagefind`, and `lint` runs ESLint with `no-console` set to error. Site settings live in `astro-paper.config.ts`, typed by `defineAstroPaperConfig` in `src/types/config.ts` and resolved with defaults in `src/config.ts`. That file already shows the pattern for an optional third-party tag: `site.googleVerification` is read from the config first and falls back to `PUBLIC_GOOGLE_SITE_VERIFICATION`, an `astro:env/client` variable declared under `env.schema` in `astro.config.ts`, and `src/layouts/Layout.astro` renders the verification `<meta>` only when a value is set.

The agent follows that pattern rather than hard-coding a provider. It adds an optional `analytics` entry to `SiteConfig` with the provider's script URL and the site identifier the provider expects, such as Plausible's `data-domain` or Umami's `data-website-id`, resolves it in `src/config.ts` with an environment fallback declared the same way as the verification variable, and renders one `<script is:inline defer>` tag in the `<head>` of `Layout.astro`, next to the verification meta, only when the entry is set and `import.meta.env.PROD` is true, so `astro dev` and preview deployments send nothing. `is:inline` matters here: without it Astro would bundle and hoist the tag, and the provider's `data-*` attributes would be lost.

Then it deals with the part most analytics guides skip. `Layout.astro` renders `<ClientRouter />` from `astro:transitions`, so a click from the index to a post is a client-side swap, not a full page load, and a script that counts views only on load would record one visit per session. `src/scripts/theme.ts` already shows how the theme listens for `astro:after-swap`; the agent reads the chosen provider's script to see whether it hooks `history.pushState` on its own and, when it does not, adds a small `astro:page-load` listener that calls the provider's page-view function. It also adds the provider's host to nothing else, because the site sets no Content-Security-Policy header, and leaves `src/i18n/lang/en.ts` alone since the tag has no visible text.

To prove it, the agent sets the option in `astro-paper.config.ts` to a placeholder domain, runs `pnpm build` and `pnpm preview`, opens the site in the sandbox's browser, navigates from the home page to a post and back, and reads the network log to confirm one request to the provider per navigation and none on the `astro dev` server. It runs `pnpm lint` and `pnpm format:check`, the same checks `.github/workflows/ci.yml` runs on every pull request with pnpm 11.3.0 and Node 24, and updates `README.md` beside the Google Site Verification section and the config table in `src/content/posts/how-to-configure-astropaper-theme.mdx` so the option is documented where the others are.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add privacy-friendly analytics to this Astro site. Read package.json, astro.config.ts, astro-paper.config.ts, src/types/config.ts, src/config.ts, src/layouts/Layout.astro and src/scripts/theme.ts first. Add an optional site.analytics option to the config types with the provider script URL and the site identifier, resolve it in src/config.ts with a PUBLIC_ environment fallback declared in astro.config.ts the same way PUBLIC_GOOGLE_SITE_VERIFICATION is, and render one is:inline deferred script tag in Layout.astro only when the option is set and the build is production. The site uses ClientRouter view transitions: make sure a client-side navigation records a page view, by relying on the provider script's history tracking if it has it or by adding an astro:page-load listener if it does not. Set the option to a placeholder domain, run pnpm build and pnpm preview, navigate between pages in a browser and confirm one analytics request per navigation and none under astro dev. Run pnpm lint and pnpm format:check, document the option in README.md next to the Google Site Verification section and in the config table in src/content/posts/how-to-configure-astropaper-theme.mdx, then remove the placeholder and open a pull request describing what you verified.",
  "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 touches six files: `src/types/config.ts` and `src/config.ts` for the option and its default, `astro.config.ts` for the new `PUBLIC_` variable in the env schema, `src/layouts/Layout.astro` for the tag, and the two documentation files. If the provider needed a listener for view transitions, a short script under `src/scripts/` joins the list. `astro-paper.config.ts` is left as it was, so merging the pull request enables nothing until the site owner sets the option or the environment variable.

The pull request description says which provider script was used, whether it tracks history changes on its own, and what the browser's network log showed for a full load, a client-side navigation and the dev server. The transcript at `GET /o/{org}/sessions/{id}/messages` holds the `pnpm build`, `pnpm preview`, `pnpm lint` and `pnpm format:check` output and the browser steps, so a reviewer can see the requests the agent counted rather than take a sentence for it.

Before merging, a reviewer checks that the tag renders only when the option is set and only in production, that the `data-*` attributes survived the build, and that the documentation names the right config key. The usual follow-up is a message on the same session asking for a second provider or for the tag to honour a do-not-track setting.

## Run it on every new Astro site repository

When a team spins up a blog or docs site from the same theme each quarter, the same prompt runs for each one. From your own server, send the body above to `POST /o/{org}/sessions` with the new repository in `resources` and a `request_id` that is a UUID v5 of the repository name, so a retried request does not start a second run. Give the key a `webhook_url` and every run the key starts posts `run.completed` with `data.session_url` when its turn ends; a handler reads the pull request link from the session and posts it where the team will see it.

For a site that already exists, start the run from the console and follow it live, or queue it as a Linear issue: an automation with a `linear` trigger on `linear.issue.labeled`, filtered to a label such as `analytics`, starts one run per labelled issue with the issue text placed after the prompt.

## Why run it on Rush?

The only honest test of an analytics tag is a browser doing what a visitor does, and with Astro's view transitions the interesting case is a navigation that never reloads the page. On a laptop that means building the site, opening a tab, watching the network panel and remembering what you saw. The agent's sandbox has a real browser, so it performs the navigation, reads the requests, and the result is written down in the pull request.

Every command it runs, from `pnpm install` to `pnpm format:check`, is kept with its output in the run's transcript, so the review is of evidence rather than of a claim. Several sites can be instrumented at once, each in its own sandbox, and each pull request is scoped to that site's config files.

## Frequently asked questions

### Which analytics provider does the agent add?

Whichever one you name in the prompt. The option it adds holds a script URL and a site identifier, so Plausible, Umami, Fathom or a self-hosted equivalent fit the same shape. If the prompt names none, the agent picks a cookie-free provider and says so in the pull request, and switching is a one-line change in `astro-paper.config.ts`.

### Will page views be counted when a reader clicks between posts?

That is the case the agent checks explicitly. `Layout.astro` uses `ClientRouter`, so navigations are client-side swaps. The agent confirms the provider script tracks `history.pushState` or adds an `astro:page-load` listener, then verifies in the sandbox browser that a navigation produces exactly one request.

### Does the tag load during development?

No. The tag renders only when the option or its environment variable is set and `import.meta.env.PROD` is true, so `astro dev` sends nothing and a build without the option set is identical to the current site.

### Can I keep the site identifier out of the repository?

Yes. The option falls back to a `PUBLIC_` environment variable declared in the `env.schema` of `astro.config.ts`, the same mechanism the theme already uses for the Google Site Verification value, so the identifier can live in your host's environment settings instead of the config file.

## More Astro jobs

- [Add Author Pages to an Astro Blog](https://getrush.ai/run/add-author-pages/astro/)
- [Add Giscus Comments to an Astro Blog](https://getrush.ai/run/add-giscus-comments/astro/)
- [Add a Second Language to an Astro Site](https://getrush.ai/run/add-i18n/astro/)

## The same job on other stacks

- [Add Analytics to an Expo App](https://getrush.ai/run/add-analytics/expo/)
- [Add Google Analytics to a Gatsby Blog](https://getrush.ai/run/add-analytics/gatsby/)

## More jobs like this: Hand off a long task

- [Add ansible-lint to CI for an Ansible Role](https://getrush.ai/run/add-ansible-lint/ansible/)

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