How to Use Fathom with Astro: Complete Guide
Step-by-step guide to integrating Fathom with your Astro website.
Fathom is a privacy-first web analytics platform that gives you the metrics you actually need without the complexity (or privacy concerns) of Google Analytics. It is GDPR, CCPA, and ePrivacy compliant out of the box, which means no cookie banners required. Fathom collects pageviews, referrers, device info, and goal conversions without tracking individual users or storing personal data.
For Astro sites, integrating Fathom takes about two minutes. You add a script tag and you are done. But there are a few patterns that make the integration work better, especially for sites with client-side navigation or islands architecture.
Prerequisites
- Node.js 18+
- An Astro project (
npm create astro@latest) - A Fathom account ($14/mo for 100,000 pageviews)
- Your Fathom site ID (found in Settings > Sites)
Installation
Fathom does not require any npm packages for basic tracking. It is a single script tag. However, if you want programmatic control for SPAs or custom events:
npm install fathom-client
Configuration
The simplest approach is adding the Fathom script to your layout. Get your site ID from the Fathom dashboard.
Add it to .env for easy management:
PUBLIC_FATHOM_SITE_ID=ABCDEFGH
Create an analytics component:
---
// src/components/Analytics.astro
const siteId = import.meta.env.PUBLIC_FATHOM_SITE_ID;
---
{siteId && (
<script
src="https://cdn.usefathom.com/script.js"
data-site={siteId}
data-auto="true"
data-spa="auto"
defer
></script>
)}
Add this component to your base layout:
---
// src/layouts/BaseLayout.astro
import Analytics from "../components/Analytics.astro";
---
<html>
<head>
<Analytics />
<!-- other head elements -->
</head>
<body>
<slot />
</body>
</html>
The data-spa="auto" attribute tells Fathom to automatically track page navigations in single-page app mode, which covers Astro's View Transitions and client-side navigation.
Basic Usage
With the script tag in place, Fathom tracks pageviews automatically. No additional code needed for basic analytics.
For custom event tracking (goal conversions), use the fathom-client package:
---
// src/components/SignupButton.astro
---
<button id="signup-btn">Start Free Trial</button>
<script>
import * as Fathom from "fathom-client";
document.getElementById("signup-btn")?.addEventListener("click", () => {
Fathom.trackEvent("signup_click");
});
</script>
If you are using View Transitions (introduced in Astro 3), make sure Fathom tracks navigation events properly:
---
// src/components/Analytics.astro
const siteId = import.meta.env.PUBLIC_FATHOM_SITE_ID;
---
{siteId && (
<script
src="https://cdn.usefathom.com/script.js"
data-site={siteId}
data-auto="false"
defer
></script>
)}
<script>
import * as Fathom from "fathom-client";
// Track initial page load
Fathom.load(import.meta.env.PUBLIC_FATHOM_SITE_ID, {
auto: false,
});
// Track each page view
function trackPageview() {
Fathom.trackPageview();
}
// Initial pageview
trackPageview();
// Track View Transitions navigations
document.addEventListener("astro:after-swap", trackPageview);
</script>
For tracking goal conversions with monetary values:
// Track a purchase event worth $49
Fathom.trackEvent("purchase_complete", { _value: 4900 }); // Value in cents
Set up goals in the Fathom dashboard to see conversion rates, revenue attribution, and funnel data alongside your pageview metrics.
Production Tips
Use custom domains for the tracking script. Fathom supports custom domains (e.g.,
stats.yourdomain.com) to serve the tracking script. This bypasses ad blockers that block third-party analytics scripts, giving you more accurate data.Track only in production. Wrap the analytics component in an environment check so you do not pollute your data with localhost pageviews during development.
{import.meta.env.PROD && siteId && (
<script src="https://cdn.usefathom.com/script.js" data-site={siteId} defer></script>
)}
Use the Fathom API for dashboards. Fathom has a REST API that lets you pull analytics data into custom dashboards or reporting tools. Use it to display visitor counts directly on your site or build internal dashboards.
Set up email reports. Fathom sends weekly or monthly email summaries of your traffic. Enable these in your site settings so you stay aware of trends without logging into the dashboard every day.
Exclude your own traffic. Fathom provides a "Block my visits" feature accessible from your site's settings. Use it on every device you regularly browse your site from to keep your analytics clean.
Alternatives to Consider
- Plausible if you want a similar privacy-first analytics platform with a lower starting price ($9/mo) and a self-hosted option.
- Umami if you want a free, open-source alternative you can self-host on your own server.
- Google Analytics if you need advanced features like user flow visualization, e-commerce tracking, and integration with Google Ads (at the cost of privacy compliance).
Wrapping Up
Fathom is the analytics tool for developers who want useful data without the guilt of tracking users. The integration with Astro is trivial, the dashboard is clean, and you never have to show a cookie consent banner. For most Astro sites, blogs, documentation, marketing pages, Fathom provides all the insights you need (page views, referrers, top pages, devices) without the overwhelming complexity of Google Analytics. At $14/month, it is a reasonable expense that saves you from dealing with GDPR compliance headaches.
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.