How to Use Plausible with Astro: Complete Guide
Step-by-step guide to integrating Plausible Analytics with your Astro website. Installation, configuration, and best practices.
Plausible is a privacy-focused analytics tool that is lightweight, GDPR-compliant, and does not use cookies. It is the opposite of Google Analytics in all the right ways. The script is under 1KB, it does not slow down your site, and you do not need a cookie consent banner. For an Astro site where performance matters, Plausible is a perfect fit.
Prerequisites
- Node.js 18+
- An Astro project (
npm create astro@latest) - A Plausible account ($9/month for 10K pageviews, or self-hosted for free)
Installation
Plausible does not need an npm package. You just add a script tag. But if you want a cleaner setup, there is a community package:
npm install @plausible/tracker
Or you can skip the package and just add the script directly, which is what most people do.
Configuration
The simplest approach is adding the Plausible script to your base layout. Add it to the <head> of your layout file:
---
// src/layouts/BaseLayout.astro
export interface Props {
title: string;
description?: string;
}
const { title, description } = Astro.props;
---
<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} />}
<!-- Plausible Analytics -->
<script
defer
data-domain="yourdomain.com"
src="https://plausible.io/js/script.js"
></script>
</head>
<body>
<slot />
</body>
</html>
Replace yourdomain.com with your actual domain. That is it. One script tag and analytics are running.
Environment-Aware Setup
You probably do not want to track development visits. Use Astro's environment detection to conditionally load the script:
---
// src/layouts/BaseLayout.astro
const isProd = import.meta.env.PROD;
const domain = "yourdomain.com";
---
<html lang="en">
<head>
{isProd && (
<script
defer
data-domain={domain}
src="https://plausible.io/js/script.js"
is:inline
></script>
)}
</head>
<body>
<slot />
</body>
</html>
Tracking Custom Events
Plausible supports custom events for tracking things like button clicks, form submissions, and signups. Add the event-tracking script variant:
<script
defer
data-domain="yourdomain.com"
src="https://plausible.io/js/script.tagged-events.js"
></script>
Then trigger events in your Astro components:
<button id="signup-btn" class="btn-primary">
Sign Up Free
</button>
<script is:inline>
document.getElementById("signup-btn")?.addEventListener("click", () => {
if (window.plausible) {
window.plausible("Signup Click", {
props: { location: "homepage" },
});
}
});
</script>
Or use CSS class-based events without any JavaScript. Add the class plausible-event-name=YourEvent to any clickable element:
<a
href="/pricing"
class="plausible-event-name=Pricing+Click btn-primary"
>
View Pricing
</a>
Tracking 404 Pages
Add 404 tracking with the appropriate script extension:
<script
defer
data-domain="yourdomain.com"
src="https://plausible.io/js/script.404.js"
></script>
Then on your 404 page:
---
// src/pages/404.astro
---
<html>
<body>
<h1>Page Not Found</h1>
<p>The page you are looking for does not exist.</p>
</body>
</html>
<script is:inline>
if (window.plausible) {
window.plausible("404", { props: { path: document.location.pathname } });
}
</script>
Using the Plausible API
Plausible has a Stats API you can use to display analytics data on your site:
// src/pages/api/stats.ts
import type { APIRoute } from "astro";
export const GET: APIRoute = async () => {
const response = await fetch(
"https://plausible.io/api/v1/stats/realtime/visitors?site_id=yourdomain.com",
{
headers: {
Authorization: `Bearer ${import.meta.env.PLAUSIBLE_API_KEY}`,
},
}
);
const visitors = await response.text();
return new Response(JSON.stringify({ visitors: parseInt(visitors) }), {
headers: { "Content-Type": "application/json" },
});
};
Production Tips
Use the self-hosted version to save money. If you have a server, self-hosting Plausible is free and gives you full control over your data. A small VPS is enough.
Proxy the script through your domain. Some ad blockers block requests to plausible.io. Set up a proxy (using Cloudflare Workers or a simple redirect) to serve the script from your own domain.
Combine script extensions. Plausible lets you stack features:
script.tagged-events.outbound-links.file-downloads.jstracks custom events, outbound links, and file downloads in one script.Set up email reports. Plausible can send you weekly or monthly traffic reports via email. No need to check the dashboard manually.
Use the shared link feature. Generate a public dashboard link to share analytics with your team or clients without giving them account access.
Alternatives to Consider
- Fathom if you want a similar privacy-first approach with slightly different pricing ($14/month for 100K pageviews). Both are excellent.
- Umami if you want a free, self-hosted, open-source analytics tool with a clean interface. Very similar to Plausible.
- Google Analytics if you need detailed conversion funnels, e-commerce tracking, or integration with Google Ads. More powerful but heavier and requires cookie consent.
Wrapping Up
Plausible gives you the analytics you actually need without the bloat, privacy issues, or consent banners. For an Astro site, it is a one-line addition that respects your users and keeps your site fast. Hard to ask for more than that.
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.