# 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
```html
```
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 ``:
astro
```astro
---
// Your frontmatter
const { title } = Astro.props;
---
{title}
```
**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
```env
PUBLIC_HUMBLYTICS_ID=YOUR_ID_HERE
```
2. Update your layout:
astro
```astro
---
const { title } = Astro.props;
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
---
{title}
{humblytics && (
)}
```
3. Add to `.env.production` (or your hosting platform's env vars):
env
```env
PUBLIC_HUMBLYTICS_ID=your_production_id_here
```
#### Option 3: Production-only tracking
**Best for:** Disabling analytics during development
astro
```astro
---
const { title } = Astro.props;
const isDev = import.meta.env.DEV;
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
---
{title}
{!isDev && humblytics && (
)}
```
#### 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 `` in your layout:
astro
```astro
---
import { ViewTransitions } from 'astro:transitions';
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
---
{title}
{humblytics && (
)}
```
**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
```astro
---
const humblytics = import.meta.env.PUBLIC_HUMBLYTICS_ID;
const isDev = import.meta.env.DEV;
---
{!isDev && humblytics && (
)}
```
**Use in layouts:**
astro
```astro
---
import Analytics from '../components/Analytics.astro';
---
{title}
```
**Note**: Replace `YOUR_ID_HERE` with your actual project ID from Humblytics.
### 4 · Build and deploy
**Development:**
bash
```bash
npm run dev
# Humblytics won't track if using production-only setup
```
**Production:**
bash
```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
```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