# Add View Transitions to an Astro Site

Yes. An agent adds the ClientRouter to your base layout, keeps the theme and menu scripts working across navigations, tests it in a browser and opens a PR.

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

## What the agent does

The agent reads the layouts and every script before turning on client-side navigation, because those scripts are what breaks. In withastro/blog-tutorial-demo on its `complete` branch, `package.json` has Astro ^7.0.3 with `@astrojs/preact` and `@astrojs/rss`, `astro.config.mjs` sets `site` and the Preact integration, and `tsconfig.json` extends `astro/tsconfigs/strict` with Preact's JSX source. `src/layouts/BaseLayout.astro` is the one layout every page uses: a head with the favicon, viewport, `Astro.generator` and a `pageTitle` prop, then `Header`, an `h1`, the slot, `Footer`, and a bundled `<script>` that imports `../scripts/menu.js`. `MarkdownPostLayout.astro` wraps it for the four posts in `src/pages/posts/*.md`, printing date, description, author, image and tag links. `Header.astro` renders `ThemeIcon`, `Menu` and `Navigation`; `ThemeIcon.astro` carries an `is:inline` script that reads `localStorage` or `prefers-color-scheme`, toggles the `dark` class on `documentElement`, and binds a click handler with `getElementById('themeToggle')`; `scripts/menu.js` binds one click handler on `.menu` that flips `aria-expanded`. `index.astro` renders a Preact `Greeting` island with `client:load`; `blog.astro`, `about.astro`, `tags/[tag].astro`, `tags/index.astro` and `rss.xml.js` complete the site. Nothing imports from `astro:transitions` today, so each link is a full page load.

The change begins with one line: `import { ClientRouter } from 'astro:transitions'` and `<ClientRouter />` in the head of `BaseLayout.astro`, which turns every internal link on every page into a client-side navigation with the browser's view transition where it is supported and a plain swap where it is not. Then the scripts. The theme script is `is:inline`, so after a swap the new document's `<html>` arrives without the `dark` class until something re-applies it; the agent moves the class-setting code into a function and calls it both on first load and from a `document.addEventListener('astro:after-swap', ...)` listener, so the new page is dark before it paints and there is no flash. The click handler for the toggle, and the `.menu` handler in `menu.js`, are bound to elements that are replaced on each navigation, so both move under `astro:page-load`, which fires on first load and after every navigation; the agent chooses listeners over the `data-astro-rerun` attribute so each script attaches exactly once per page and says why in the pull request.

Two small touches make the result visible. The post title gets a `transition:name` derived from the post's slug in both `blog.astro`'s list and `MarkdownPostLayout.astro`'s heading, so clicking a post animates its title into place, and the `Header` gets `transition:persist` so the open menu state survives moving between pages. The Preact `Greeting` island needs nothing, since the router hydrates islands on the new page as it would on a load. `rss.xml.js` is a non-HTML endpoint and is untouched.

Checking happens in a real browser, which the sandbox has. The agent runs `npm run build`, then `npm run preview`, opens the site, and navigates Home to Blog to a post to Tags, confirming on each step that no full load happened, that the `dark` class is still present after each swap when the theme is dark, that the menu toggle and theme toggle still respond, and that the feed at `/rss.xml` still serves. It also toggles the system's reduced-motion preference, under which the router skips the animations by default, and records that the pages still swap.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add view transitions to this Astro site. Read package.json, astro.config.mjs, every file under src/layouts, src/components, src/scripts and src/pages first, and list every script and where it binds to the DOM. Add the ClientRouter from astro:transitions to the base layout's head. Make the inline theme script re-apply the dark class on astro:after-swap and bind its click handler on astro:page-load, and move the menu script's handler under astro:page-load as well, so neither double-binds; explain why you chose lifecycle events over data-astro-rerun. Give post titles a transition:name shared between the blog list and the post layout, persist the header across navigations, and leave the RSS endpoint and the Preact island alone. Build the site, serve the preview, and in the browser navigate between the home, blog, a post and the tags pages checking that no full load occurs, that the dark theme survives each navigation, that both toggles still work and that the feed still serves; check once with reduced motion on. Open a pull request that lists each script you changed and what you observed in the browser.",
  "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 that edits `src/layouts/BaseLayout.astro`, `src/layouts/MarkdownPostLayout.astro`, `src/components/Header.astro`, `src/components/ThemeIcon.astro`, `src/scripts/menu.js` and `src/pages/blog.astro`. Its description lists each script with the event it now listens on and why, names the shared transition on post titles, and reports what the agent saw in the browser on each navigation.

The run's record keeps the `astro build` output and the browser session, so a reviewer can watch the navigations and the dark class persisting without rebuilding the site themselves.

Before merging, a reviewer opens the preview on the pull request's deploy, tries the theme toggle after two or three navigations, and checks a browser without native view transitions to confirm the swap still happens with no animation, which is the fallback the router promises.

## Run it on every Linear issue labelled site

A team that tracks website work in Linear adds an automation with a `linear` trigger on `linear.issue.labeled` for the label `site`, the Project that holds this repository, and this prompt. Labelling the issue that asks for smoother navigation starts one run; the issue's text is added after the prompt, so a request for a particular animation or for excluding a page reaches the agent as written.

The trigger fills in no placeholder, so the next site issue on the same automation, a prefetch strategy or a scroll restoration fix, only needs to say what the visitor should see.

## Why run it on Rush?

Turning on client-side routing is one line; the work is every script that assumed a fresh document, and the only way to know which ones you missed is to click through the site after the change. The agent does that in its own sandbox with a real browser, checks the exact states that break, the theme class after a swap and handlers on replaced elements, and keeps the session in the run's record.

The pull request explains each script change against the router's lifecycle events rather than leaving a reviewer to rediscover why the theme flashed, which is the difference between a change that gets merged and one that gets reverted a week later.

## Frequently asked questions

### Why ClientRouter and not ViewTransitions?

`ClientRouter` is the component Astro exports from `astro:transitions` for client-side navigation with view transitions; it is the current name of the component earlier versions called `ViewTransitions`. On Astro 7 the agent imports `ClientRouter`, and the pull request notes the old name for readers following older tutorials.

### Why not just add data-astro-rerun to the inline script?

`data-astro-rerun` makes an inline script execute again after every transition, which would re-read the theme and rebind the click handler, but it also re-runs everything else in the script each time. Listening on `astro:after-swap` for the class and `astro:page-load` for the handler attaches once and runs exactly the needed code at the right moment, which is easier to reason about as the script grows.

### What happens in a browser without the View Transitions API?

The router still intercepts links, fetches the next page and swaps the document, so navigation stays client-side; only the animation is skipped. The agent checks this path and the reduced-motion path in the browser, and the pull request reports both.

### Does the Preact island keep working?

Yes. The `Greeting` island on the home page is rendered with `client:load`, and the router hydrates islands on the incoming page the same way a full load does. The agent confirms the island responds after navigating away and back; `transition:persist` on an island is only needed when its state must survive, which this one has no need for.

## More Astro jobs

- [Fix a Failing CI Build for an Astro Site](https://getrush.ai/run/fix-failing-ci/astro/)
- [Turn Sentry Errors Into Fix Pull Requests for an Astro Site](https://getrush.ai/run/fix-sentry-errors/astro/)
- [Fix a Failed Vercel Deployment of an Astro Site](https://getrush.ai/run/fix-vercel-build-failures/astro/)

## More jobs like this: Turn a Linear label into a PR

- [Add AWS WAF to an API Gateway REST API in AWS CDK](https://getrush.ai/run/add-waf/aws-cdk/)
- [Add a Getting Started Walkthrough to a VS Code Extension](https://getrush.ai/run/add-walkthrough/vscode-extension/)
- [Add a Watchlist Page to a Nuxt App from a Linear Issue](https://getrush.ai/run/add-watchlist/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/)
