All jobs

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

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

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

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

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading