# 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.humblytics.com/how-to-get-started/astro.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.