How to add analytics to an Astro site

Astro processes and bundles <script> tags by default. An analytics tag must reach the browser exactly as written — external src, defer, and the data-site attribute the tracker reads — so mark it is:inline. (Astro already treats any script with attributes besides src as inline; writing it explicitly just makes the intent obvious to the next person.)

How to install VisitTrack on Astro

1. 1

   Step 1: Copy your site id

   Add the site in VisitTrack and copy the snippet from the install step (or Settings → General). Replace SITE_ID below.

2. 2

   Step 2: Add the tag to your base layout

   Open the layout that renders <html> and <head> for every page. If you have several layouts, put it in the one they all extend — or in a shared BaseHead.astro component used by each.

   src/layouts/Layout.astroCopy

   ---
   const { title } = Astro.props;
   ---
   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <title>{title}</title>
       <script is:inline defer data-site="SITE_ID" src="https://visitrack.app/tracker.js"></script>
     </head>
     <body>
       <slot />
     </body>
   </html>

3. 3

   Step 3: Using view transitions? Keep the tag in the head only

   With <ClientRouter />, Astro swaps the page in the browser and compares the old and new <head>. Because every page renders the identical tag from the same layout, it's kept as it is rather than run again. Don't add data-astro-rerun to it — that forces a re-run on every navigation and would double-count.

4. 4

   Step 4: Build, deploy and open the site

   astro dev serves on localhost, which the tracker ignores. Deploy (or run astro preview with data-allow-local temporarily) and browse a few pages.

How to check VisitTrack is working on Astro

1. View source on a deployed page: the tag appears in <head> exactly as written, not rewritten into a bundled module.
2. Open two or three pages; the VisitTrack live view shows you, and the Pages tab lists each path.
3. With <ClientRouter />, DevTools → Network should show exactly one POST to visitrack.app/api/collect per navigation, not two.

Does VisitTrack track Astro page navigation?

Without view transitions, each page is a full page load and gets its pageview on load. With <ClientRouter />, Astro's router updates the URL with history.pushState (or replaceState for data-astro-history="replace" links), which the tracker wraps — so soft navigations are pageviews too. You don't need an astro:page-load listener for VisitTrack.

Pageviews are keyed on the pathname, so a link that only changes the #hash or the query string isn't counted again.

How to track custom events and goals in Astro

On a mostly static site, the attribute-based events do most of the work: data-vt-goal="newsletter_cta" records a click on any element, and data-vt-scroll="pricing_viewed" fires once when that element is at least half visible. Both are re-scanned after client-side navigations.

For logic, call window.visitrack() from a client script. In a regular (bundled) Astro <script>, it runs once per page load; with view transitions, put per-page code in an astro:page-load listener.

<a href="/pricing" data-vt-goal="pricing_cta">See pricing</a>

<form id="newsletter">…</form>
<script>
  document.addEventListener("astro:page-load", () => {
    const form = document.getElementById("newsletter");
    form?.addEventListener("submit", () => window.visitrack?.("newsletter_signup"));
  });
</script>

Automatic events are on by default too: file downloads, mailto:/tel: clicks, form submits, rage clicks, JavaScript errors and 404 pages (Astro's 404.astro title usually contains "404" or "not found", which is what the tracker checks).

Script options you might need on Astro

All optional — add them to the same tag. Full reference: script configuration.

Astro troubleshooting

Not on Astro? See all 29 integration guides.