Astro

Add Humblytics Analytics to an Astro Site

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

Open your main layout file:
- src/layouts/BaseLayout.astro
- Or src/layouts/Layout.astro
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)

Add to .env:

env

PUBLIC_HUMBLYTICS_ID=YOUR_ID_HERE

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>

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:

Add the script to each layout, or
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

Return to Humblytics and click Verify Website
Open your live Astro site in a private/incognito window
Refresh once
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

PreviousGetting Started NextBolt

Last updated 1 month ago

Was this helpful?

Add Humblytics Analytics to an Astro Site

1 · Sign up (or log in)

2 · Add your website in Humblytics

3 · Add the script to your Astro project

Option 1: Direct script tag (simplest)

Option 2: Using environment variables (recommended)

Option 3: Production-only tracking

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

Multiple layouts

4 · Build and deploy

5 · Verify installation

6 · Explore & optimize