Adding Analytics to Your Astro Site

Astro renders most components to static HTML by default. Adding a tracking script works the same way as any HTML site — with one consideration for Astro's is:inline directive.

Astro basics for analytics

Astro pages are rendered on the server (or at build time for static sites). Client-side JavaScript is opt-in through Astro's island architecture.

For analytics, you want a script that runs in the visitor's browser, not at build time. Use the standard <script> tag approach.

Adding Antlytics to an Astro site

Place the tracking snippet in your base layout component (src/layouts/BaseLayout.astro or similar):

---
// src/layouts/BaseLayout.astro
const { title } = Astro.props
---
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <script is:inline>
    (function(){
      var t="YOUR_TRACKING_ID",
          u="https://www.antlytics.com/api/ingest/pageview",
          k="ant_sid";
      function sid(){
        try{var s=sessionStorage.getItem(k);if(s)return s;
        s=crypto.randomUUID();sessionStorage.setItem(k,s);return s;}
        catch(e){return crypto.randomUUID();}
      }
      function send(){
        fetch(u,{method:"POST",headers:{"Content-Type":"application/json"},
        keepalive:true,body:JSON.stringify({tracking_id:t,
        pathname:location.pathname,referrer:document.referrer||undefined,
        session_id:sid()})}).catch(function(){});
      }
      send();
      window.addEventListener("popstate",send);
    })();
    </script>
  </head>
  <body>
    <slot />
  </body>
</html>

The is:inline directive tells Astro to include the script exactly as written — without processing or bundling it. This is important because the analytics script should remain inline for performance.

Replace YOUR_TRACKING_ID with the UUID from your Antlytics dashboard.

Verifying pageviews

Run astro dev and open your site in a browser.
Open the network tab in browser dev tools.
Navigate to a page — you should see a POST request to /api/ingest/pageview.
Open your Antlytics dashboard and confirm a visitor appears.

SSR considerations

If you are using Astro in SSR mode (output: 'server'), the script still runs in the browser — SSR only affects how the HTML is generated, not how client scripts execute. The same setup works for both static and SSR Astro sites.

SPA navigation

If your Astro site uses view transitions (<ViewTransitions />), pages do not do full reloads on navigation. The popstate event may not fire on all transitions.

For Astro View Transitions, add a listener for the astro:page-load event:

<script is:inline>
  function sendPageview() {
    // ... your tracking function here
  }
  sendPageview();
  document.addEventListener("astro:page-load", sendPageview);
</script>

This ensures a pageview fires on both initial load and every View Transitions navigation.

FAQ

Does Antlytics have an Astro integration package? See the Astro docs for the current recommended approach.

Can I use the @antlytics/analytics npm package with Astro? The npm package is designed for React/Next.js. For Astro, the script tag approach is recommended.

What about Astro Content Collections? Content Collections are a build-time feature — they do not affect how the analytics script runs in the browser.