Adding Analytics to Your Astro Site

Astro renders most components to static HTML by default. Adding the hosted Antlytics tracker works the same way as any HTML site — with one consideration for Astro's is:inline directive if you paste the script yourself.

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. Prefer the official @antlytics/astro integration, or drop in the hosted tracker.js snippet.

Option A — `@antlytics/astro` integration (recommended)

npm install @antlytics/astro

// astro.config.mjs
import { defineConfig } from 'astro/config'
import { antlytics } from '@antlytics/astro'

export default defineConfig({
  integrations: [
    antlytics({ trackingId: 'YOUR_TRACKING_ID' }),
  ],
})

The integration injects the hosted tracker on every page. See the Astro docs.

Option B — Hosted script in your layout

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
      defer
      src="https://www.antlytics.com/tracker.js"
      data-tracking-id="YOUR_TRACKING_ID"
      data-api-host="https://www.antlytics.com"
    ></script>
  </head>
  <body>
    <slot />
  </body>
</html>

If Astro processes the tag unexpectedly in your setup, add is:inline so the attributes stay as written. Replace YOUR_TRACKING_ID with the UUID from your Antlytics dashboard. Same snippet as Quick start.

Verifying pageviews

Run astro dev and open your site in a browser.
Open the network tab in browser dev tools.
Confirm tracker.js loads and a POST request fires 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 / View Transitions

If your Astro site uses view transitions (<ViewTransitions />), pages do not do full reloads on navigation. The hosted tracker still captures client-side navigation via History API patches and popstate — no extra astro:page-load listener required.

FAQ

Does Antlytics have an Astro integration package? Yes — @antlytics/astro. See the Astro docs.

Can I use the @antlytics/analytics npm package with Astro? That package is designed for React/Next.js (@antlytics/analytics/next). For Astro, use @antlytics/astro or the hosted script tag.

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