Skip to content

How to Add Plausible Analytics to Gatsby

Created: Nov 12, 2021 – Last Updated: Aug 22, 2023

Tags: Gatsby

Digital Garden

You’re a fan of Plausible Analytics (opens in a new tab) and Gatsby (opens in a new tab)? Great! In this guide you’ll learn how to add Plausible Analytics to your Gatsby site, including support for TypeScript, 404 error page tracking, and custom events.

You should already have set up an account with Plausible and have your domain name at hand. It’s the name in the URL:<your-name>. Also want to learn how to use Deferred Static Generation with Plausible? You can also check out the post Using Deferred Static Generation with Analytics Tools afterwards.


Edit the gatsby-ssr.jsx to add the tracking script. You can choose between a variety of script extensions (opens in a new tab) – you can edit it in the SCRIPT_URI variable. This also adds the snippet for 404 error page tracking (opens in a new tab).

import * as React from "react"
const SITE_DOMAIN = `your-domain`
const SCRIPT_URI = `/js/script.js`
export const onRenderBody = ({ setHeadComponents }) => {
if (process.env.NODE_ENV === `production`) {
const scriptProps = {
"data-domain": SITE_DOMAIN,
src: `https://${PLAUSIBLE_DOMAIN}${SCRIPT_URI}`,
return setHeadComponents([
<script key="plausible-script" defer {...scriptProps} />,
// See:
__html: `
window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) };
return null

Edit the gatsby-browser.jsx to add pageview tracking:

export const onRouteUpdate = () => {
if (
process.env.NODE_ENV === `production` &&
typeof window.plausible !== `undefined`
) {


In order to have IntelliSense on the custom events you’ll need to declare Plausible on the global window element. Create a declaration file or reuse your existing one with the following contents:

declare global {
interface Window {
plausible: (
name: string,
options?: { callback?: () => void; props?: { [key: string]: string } }
) => void

#404 Error Page Tracking

Besides adding the custom event to the src/pages/404.jsx page you’ll also need to create a custom event goal in Plausible. See their documentation (opens in a new tab) to learn more.

Here’s an example of a 404 Page written in TypeScript:

import * as React from "react"
import { PageProps } from "gatsby"
const NotFound: React.FC<PageProps> = () => {
React.useEffect(() => {
window.plausible(`404`, { props: { path: document.location.pathname } })
}, [])
return <main>404 - Not Found</main>
export default NotFound

Want to learn more? Browse my Digital Garden