Agent Compatibility in Single-Page Apps

Why single-page apps trip agents up

In a traditional site every click on a link asks the server for a new page. The address changes, the browser shows a new title, the back button works and the server can say "this page does not exist" with a 404. Agents are built around those signals.

A single-page app replaces all of that with JavaScript. The router listens for clicks, swaps components and, if the developers remembered, updates the address with the History API. Each of those steps is optional, and each one that is skipped removes a signal an agent uses:

• No real link. A div or button with a click handler that calls navigate() has no address. An agent that reads links from the page does not know it leads anywhere, and cannot open it in a new tab to check.
• No address for the view. The product, the step of a booking or the filtered list exists only in memory. If the agent reloads, shares the link with its user or comes back later, it lands on the home page.
• No visible page change. The title stays the same and focus stays on the old button, so an agent reading the accessibility tree may not notice that anything happened.
• No honest status code. The server returns the same HTML shell with 200 for every address, including ones that do not exist, so the agent cannot tell a missing product from a slow one.
• Nothing to read before scripts run. Without server rendering, the first HTML is an empty shell. That problem is covered in fixing JavaScript-only content; this guide deals with what happens after.

A ten-minute check of your app

Run the AI Agent Compatibility audit on a few addresses inside the app, not just the home page, then try these checks by hand.

1. Right-click the main navigation items, product tiles and "next" buttons. If the browser does not offer "Open link in new tab" or "Copy link address", they are not links.
2. Copy the address of a product, a filtered list and step two of a booking, then open each in a new private window. Every one should show the same view, not the home page, a blank screen or a server error.
3. Use the back and forward buttons after changing a filter or tab. They should step through the states you visited.
4. Watch the browser tab title as you move around. It should change for each view.
5. Request an address that does not exist:

   curl -s -o /dev/null -w "%{http_code}\n" https://app.example.com/products/does-not-exist

   A result of 200 means the server is claiming the page exists.
6. Tab through the page with the keyboard only. Controls you cannot reach or operate this way will also trouble agents; the React accessibility guide goes deeper on this.

The fix, step by step

Code patterns that make the difference

Links, not click handlers

// Hard for agents: no address, not a link
<div className="tile" onClick={() => navigate(`/products/${p.slug}`)}>
  {p.name}
</div>

// Works for everyone: a real anchor with client-side routing
import { Link } from 'react-router';
<Link className="tile" to={`/products/${p.slug}`}>{p.name}</Link>

In Vue the equivalent is <RouterLink :to="`/products/${p.slug}`">, in Angular <a [routerLink]="['/products', p.slug]">, and in Next.js <Link href={`/products/${p.slug}`}> from next/link.

Deep links on the server

For a client-rendered app served by nginx, this sends real files when they exist and the app's shell for everything else, so deep links load:

location / {
    try_files $uri $uri/ /index.html;
}

That rule returns 200 for every unknown address, which is exactly the soft 404 problem. It is acceptable only as a stopgap while you move to server rendering, where the app can decide the status for each request. On Netlify the equivalent is a _redirects rule of /* /index.html 200, with the same caveat.

Filters in the address

import { useSearchParams } from 'react-router';

function Filters() {
  const [params, setParams] = useSearchParams();
  const size = params.get('size') ?? '';
  return (
    <label>Size
      <select value={size}
        onChange={e => setParams(p => { p.set('size', e.target.value); return p; })}>
        <option value="">Any</option>
        <option value="9">UK 9</option>
        <option value="10">UK 10</option>
      </select>
    </label>
  );
}

Choosing a size now produces an address such as /boots?size=9 that can be reloaded, shared and stepped back through.

Focus after navigation

// After each route change, move focus to the new view's heading
useEffect(() => {
  document.querySelector('main h1')?.focus();
}, [location.pathname]);
// The h1 needs tabIndex={-1} so it can receive focus without joining the tab order

Framework by framework

Framework defaults change between major versions, so check the documentation for the version you run rather than relying on a blog post from two years ago.

Edge cases in app-style sites

• Modals that act as pages. A product quick-view or a sign-up dialog with no address cannot be linked to. For anything with meaningful content, give it a route, even if it opens as an overlay.
• Infinite scroll. Lists that load more as you scroll hide everything beyond the first batch from agents that do not scroll. Add paginated addresses such as ?page=3 with real links, and keep infinite scroll as an enhancement on top.
• Hydration gaps. Server-rendered buttons that do nothing until the app hydrates look clickable to an agent. Use real forms and links that work before hydration, or keep the time to hydration short.
• Service workers. An old service worker can keep serving a cached shell after you deploy server rendering. Version your service worker and test in a fresh profile.
• Signed-in areas. Agents act for a real person and will hand over for sign-in. Make sure the return address after sign-in brings them back to the page they were on, not the dashboard.

Related problems covered elsewhere

Single-page apps often have the other problems the audit looks for as well. Rather than repeat them here:

• Menus that open only on hover or icon buttons with no name: fixing navigation.
• Custom form controls, generated field IDs and multi-step forms: fixing forms.
• Large bundles and slow time to usable: fixing slow rendering.
• Session timeouts and CAPTCHAs in the purchase flow: fixing checkouts.