How to Use Umami with Astro: Complete Guide
Step-by-step guide to integrating Umami with your Astro website.
Umami is an open-source, privacy-focused web analytics tool that gives you the data you actually need without the bloat of Google Analytics. No cookies, no personal data collection, and full GDPR compliance out of the box. You can self-host it for free or use their cloud service for $9 per month.
For Astro sites, Umami is a particularly good fit. The tracking script is under 2KB, it does not slow down your pages, and you do not need a cookie consent banner. Setup takes about five minutes.
Prerequisites
- Node.js 18+
- An Astro project (
npm create astro@latest) - An Umami instance (self-hosted or Umami Cloud at umami.is)
Installation
Umami does not require an npm package. It works through a single script tag. But first, you need a running Umami instance.
Option 1: Umami Cloud (easiest)
Sign up at umami.is, create a website, and get your tracking code.
Option 2: Self-hosted with Docker (free)
git clone https://github.com/umami-software/umami.git
cd umami
docker compose up -d
This starts Umami on port 3000 with a PostgreSQL database. Default login is admin / umami.
Once Umami is running, add a new website in the dashboard and copy the website ID.
Configuration
Add your Umami configuration to .env:
PUBLIC_UMAMI_WEBSITE_ID=your_website_id
PUBLIC_UMAMI_SRC=https://your-umami-instance.com/script.js
If you are using Umami Cloud, the script source is https://cloud.umami.is/script.js.
Basic Usage
Add the Umami tracking script to your base layout. The cleanest approach is to include it in the <head> of your layout component:
---
// src/layouts/BaseLayout.astro
export interface Props {
title: string;
description?: string;
}
const { title, description } = Astro.props;
const umamiId = import.meta.env.PUBLIC_UMAMI_WEBSITE_ID;
const umamiSrc = import.meta.env.PUBLIC_UMAMI_SRC;
---
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{title}</title>
{description && <meta name="description" content={description} />}
{umamiId && umamiSrc && (
<script
defer
src={umamiSrc}
data-website-id={umamiId}
/>
)}
</head>
<body>
<slot />
</body>
</html>
That is it for basic pageview tracking. Every page that uses this layout will be tracked automatically.
For custom event tracking, use Umami's JavaScript API. This is useful for tracking button clicks, form submissions, or other interactions:
---
// src/components/NewsletterForm.astro
---
<form id="newsletter-form">
<input type="email" placeholder="Your email" required />
<button type="submit">Subscribe</button>
</form>
<script>
const form = document.getElementById("newsletter-form");
form?.addEventListener("submit", () => {
// Track the event in Umami
if (typeof umami !== "undefined") {
umami.track("newsletter-signup");
}
});
</script>
You can also track events with additional data:
umami.track("button-click", { label: "pricing-cta", position: "hero" });
Production Tips
Disable tracking in development. Add a check so the script only loads in production. You can use
import.meta.env.PRODin Astro to conditionally render the script tag, keeping your dev analytics clean.Self-host for zero cost. Umami runs well on minimal hardware. A $5/month VPS handles millions of pageviews. Deploy it alongside your other services using Docker Compose.
Use the Umami API for custom dashboards. Umami exposes a REST API for querying your analytics data. You could build a custom stats page on your Astro site that pulls data directly from Umami.
Track outbound links. Add
data-umami-event="outbound-link"to external links to track which outbound links your visitors click. This helps measure affiliate performance and content effectiveness.Set up multiple websites. If you run several Astro sites, a single Umami instance can track all of them. Create a separate website entry for each domain in the Umami dashboard and use different website IDs.
Alternatives to Consider
- Plausible if you want a hosted privacy-focused analytics service with a slightly more polished dashboard and email reports built in.
- Fathom if you need a privacy-first tool with advanced features like custom domains for the tracking script and EU isolation.
- Google Analytics if you need detailed user behavior data, conversion funnels, and integration with Google Ads. The tradeoff is a heavier script and the need for cookie consent.
Wrapping Up
Umami gives you the analytics you need without the privacy baggage. For Astro sites, the integration is a single script tag. No npm packages, no build plugins, no configuration complexity. You get pageviews, referrers, device stats, and custom events in a clean dashboard. If you care about your visitors' privacy and want an analytics tool that respects it, Umami is the best open-source option available.
Related Articles
How to Use Algolia with Astro: Complete Guide
Step-by-step guide to integrating Algolia with your Astro website.
How to Integrate Auth0 with Astro: Complete Guide
Step-by-step guide to integrating Auth0 with your Astro website. Setup, configuration, and best practices.
How to Use AWS Amplify with Astro: Complete Guide
Step-by-step guide to integrating AWS Amplify with your Astro website.