Astro

Add Humblytics Analytics to an Astro Site

1 · Sign up (or log in)

Visit humblytics.com → Start Free Trial. Finish signup—or log in to your existing workspace.

2 · Add your website in Humblytics

In the sidebar, click Add Website.

  • Domain – enter your-domain.com (omit https:// and www)

  • Site Name – internal label (e.g. Astro-Site)

Copy the snippet from Install Tracking Code:

html

<!-- Start Humblytics Tracking Code -->
<script async src="https://app.humblytics.com/hmbl.min.js?id=YOUR_ID_HERE"></script>
<!-- End Humblytics Tracking Code -->

Keep this tab open—we'll return and click Verify Website once the tag is live.

3 · Add the script to your Astro project

Option 1: Direct script tag (simplest)

Best for: Quick setup, works with all Astro features

  1. Open your main layout file:

    • src/layouts/BaseLayout.astro

    • Or src/layouts/Layout.astro

  2. Add the script before </head>:

astro

---
// Your frontmatter
const { title } = Astro.props;
---

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
    
    <!-- Humblytics Analytics -->
    <script is:inline async src="https://app.humblytics.com/hmbl.min.js?id=YOUR_ID_HERE"></script>
  </head>
  <body>
    <slot />
  </body>
</html>

Note: is:inline prevents Astro from bundling/optimizing this script, ensuring it loads as-is.

Option 2: Using environment variables (recommended)

Best for: Managing different environments (dev, staging, production)

  1. Add to .env:

env

PUBLIC_HUMBLYTICS_ID=YOUR_ID_HERE

  1. Update your layout:

astro

---
const { title } = Astro.props;
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
---

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
    
    <!-- Humblytics Analytics -->
    {humblytics && (
      <script is:inline async src={`https://app.humblytics.com/hmbl.min.js?id=${humblytics}`}></script>
    )}
  </head>
  <body>
    <slot />
  </body>
</html>

  1. Add to .env.production (or your hosting platform's env vars):

env

PUBLIC_HUMBLYTICS_ID=your_production_id_here

Option 3: Production-only tracking

Best for: Disabling analytics during development

astro

---
const { title } = Astro.props;
const isDev = import.meta.env.DEV;
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
---

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
    
    <!-- Humblytics Analytics (production only) -->
    {!isDev && humblytics && (
      <script is:inline async src={`https://app.humblytics.com/hmbl.min.js?id=${humblytics}`}></script>
    )}
  </head>
  <body>
    <slot />
  </body>
</html>

Option 4: With View Transitions (if using Astro's SPA mode)

Best for: Sites using View Transitions for SPA-like navigation

If you're using <ViewTransitions /> in your layout:

astro

---
import { ViewTransitions } from 'astro:transitions';
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
---

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{title}</title>
    <ViewTransitions />
    
    <!-- Humblytics Analytics -->
    {humblytics && (
      <script is:inline async src={`https://app.humblytics.com/hmbl.min.js?id=${humblytics}`}></script>
    )}
    
    <!-- Track page views on navigation -->
    <script is:inline>
      document.addEventListener('astro:page-load', () => {
        if (window.hmbl && window.hmbl.trackPageview) {
          window.hmbl.trackPageview();
        }
      });
    </script>
  </head>
  <body>
    <slot />
  </body>
</html>

Note: The astro:page-load event ensures tracking works with client-side navigation.

Multiple layouts

If your site uses multiple layout files, either:

  1. Add the script to each layout, or

  2. Create a shared component:

Create src/components/Analytics.astro:

astro

---
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
const isDev = import.meta.env.DEV;
---

{!isDev && humblytics && (
  <script is:inline async src={`https://app.humblytics.com/hmbl.min.js?id=${humblytics}`}></script>
)}

Use in layouts:

astro

---
import Analytics from '../components/Analytics.astro';
---

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>{title}</title>
    <Analytics />
  </head>
  <body>
    <slot />
  </body>
</html>

Note: Replace YOUR_ID_HERE with your actual project ID from Humblytics.

4 · Build and deploy

Development:

bash

npm run dev
# Humblytics won't track if using production-only setup

Production:

bash

npm run build
npm run preview  # Test production build locally

Deploy to your hosting platform:

  • Vercel: vercel --prod

  • Netlify: netlify deploy --prod

  • Cloudflare Pages: Push to Git

  • Or use Astro's adapters for SSR deployments

5 · Verify installation

  1. Return to Humblytics and click Verify Website

  2. Open your live Astro site in a private/incognito window

  3. Refresh once

  4. Within ~30 seconds you should see a green Verified badge and live visitor count

If verification fails, check:

Astro-specific issues:

  • You built and deployed to production (not testing npm run dev)

  • Environment variable is set correctly (check deployment platform)

  • Script has is:inline directive (otherwise Astro may bundle it incorrectly)

  • If using View Transitions, verify astro:page-load listener is present

  • Check build output for errors: npm run build

General issues:

  • Script ID matches your project in Humblytics

  • View page source (right-click → View Page Source) and search for "humblytics"

  • Open Developer Tools (F12) → Network tab and search for hmbl.min.js

  • No ad-blockers or browser extensions are blocking the script

Debug in Astro:

bash

# Check environment variables
npm run build -- --verbose

# Test production build locally
npm run preview

6 · Explore & optimize

  • Dashboard – view traffic, top pages, and referrers

  • Heatmaps – auto-generated click and scroll insights

  • Experiments – create A/B tests directly from Humblytics

PreviousReplitNextWebflow

Last updated

Was this helpful?