DEV Community: John Schmidt

Displaying a View Counter with Plausible Analytics API Data

John Schmidt — Tue, 15 Feb 2022 15:04:38 +0000

Whilst rebuilding my personal homepage, I wanted to implement a simple view counter for my posts. I've seen this a few times on popular blogs (e.g. Lee Robinson) and thought it would be a nice thing to build.

Usually, these kinds of view counters involve some kind of database-API setup. Hence, I thought of multiple possibilities such as PlanetScale, Upstash or even a more custom approach with Prisma and some kind of self-hosted database. I do have an own VPS running in Germany, which currently only homes my self-hosted Plausible Analytics instance.

Using Plausible Analytics to retrieve the data

This was when I realized that my Analytics instance already has all the data I need. I just needed to retrieve the data to display. Plausible recently released an API - allowing us to perform the intended. So let's get right to it.

Creating an API token in Plausible

To work with our API, we first need to create an API token in our Plausible Analytics dashboard. You can find the corresponding option in your user settings.

Setting up an API route

First, I created an API route in my Next.js project. I wanted to retrieve the data according to the individual and unique post slug. Thus, the API retrieves its parameter via the URL: /api/views/[slug].ts. A first draft of the API route is shown below.

const viewsHandler = async (req: NextApiRequest, res: NextApiResponse) => {
  // Retrieve the slug from the query parameters
  const { slug } = req.query
  // If no slug is provided, return a 400
  if (!slug) {
    return res.status(400).message("Bad request")
  }
  // Handle the API request and return the data
  // ...
}

export default viewsHandler

Retrieving the data

Now we can fetch our data from the Plausible API. We need to send a GET request to our API endpoint and query for the needed information. We are going for the /api/v1/stats/aggregate endpoint because we want to cumulate a set of data (in our case, the views) into one value. The API needs a few parameters in the following syntax to provide us with the needed data:

/api/v1/stats/aggregate?site_id=_<SITE_ID>_&period=_<PERIOD>_&filters=event:page==_<SLUG>_

(I've marked the placeholders with a set of brackets like this: <PLACEHOLDER>)

Let's break this down:

site_id is the site's domain name set in the Plausible dashboard. In my case, it's johnschmidt.de
period defines a time period to retrieve the data from. Here, I wanted to retrieve allviews from the beginning. Thus, the usual periods like 6 months, 12 months or last 7 days didn't work out. Fortunately, Plausible provides us with the possibility to define a custom date range.
filters offers a few methods to filter your data. In our case, I wanted to filter by the corresponding page slug. We filter by event and deliver the exact slug in the page sub-filter. Read more on filters in the API documentation.

Providing the date range range

The API filter accepts a custom date range with two commas separated dates in a YYYY-MM-DD format. Therefore, I set my start date to the day I started using Plausible on my homepage and retrieve the current date with a bit of JavaScript slickness.

const now = new Date()
const [nowDate] = now.toISOString().split("T")
// nowDate now yields a YYYY-MM-DD format of the current date

Putting the pieces together

Now we got all the required parts and can put together our function to retrieve the all-time view count to a given page slug.

const fetcher = (input: RequestInfo, init?: RequestInit | undefined) =>
  fetch(input, init).then((res) => res.json())

async function getPlausibleViews(slug: string) {
  const url = `https://stats.johnschmidt.cloud/api/v1/stats/aggregate?site_id=johnschmidt.de&period=custom&date=2020-12-29,${nowDate}&filters=event:page==/post/${slug}`
  return fetcher(url, {
    headers: {
      Authorization: `Bearer ${process.env.PLAUSIBLE_API_KEY}`,
      Accept: "application/json",
    },
  })
}

You can see that I'm pointing the request to my personal instance of Plausible Analytics, hosted on my private VPS. If you're using Plausible's hosted solution, just replace the domain with plausible.io. I also set up a custom fetcher function to simplify the data transformation and yield the response data as serialized JSON.

⚠️ API limits
Plausible defaults to an API rate limit of 600 requests per hour. If you're self-hosting, there's a way to change this limit to avoid any blocked requests. If you're on the Plausible cloud service, you'd have to contact their team.

We need to authorize the request with our API token. I'd recommend putting the key in a private environment variable and retrieve it in the function.

Debugging our request will show that the API responds with the following data (the value is based on a random request I made for one of my pages).

{
  "results": {
    "visitors": {
      "value": 520
    }
  }
}

Now we just need to process the data, maybe clean it up a bit and put it in the API response. Let's put it all together.

const viewsHandler = async (req: NextApiRequest, res: NextApiResponse) => {
  const { slug } = req.query
  if (!slug) {
    return res.status(400).send("Bad request")
  }
  try {
    const data = await getPlausibleViews(String(slug))
    return res.status(200).json({
      requestedSlug: slug,
      date: now.toUTCString(),
      views: data?.results?.visitors?.value,
    })
  } catch (err) {
    console.error(err)
    return res.status(500).json({ err })
  }
}

export default viewsHandler

Nice, well done. Test our your new API route with some sample slugs and see if it responds with the wanted data. Let's move on and see how we can display the data on our frontend.

Displaying the data on your frontend

You might have noticed that I am primarily using Next.js as my frontend solution. Thus, the following explanation targets a Next.js frontend.

A simple way to display your API data and even give it the ability to update in real-time is to use a client-side query library like Vercel's swr or react-query. In this example, I'll be using swr.

Create a DisplayViews component

All right, let's create a component to display our data and use the revalidation features of swr. You can read more about the usage of SWR ontheir documentation website. We're going to use the basic useSWR hook and target our API route. We provide the slug of interest via a property.

import { fetcher } from "lib/fetcher"
import useSWR from "swr"

type Props = {
  slug: string
}

const DisplayViews: React.FC<Props> = ({ slug }) => {
  // Fetch the data with the useSWR hook
  const { data, error } = useSWR(`/api/views/${slug}`, fetcher)
  // If there's no data and no error, display a loading state
  if (!data && !error)
    return (
      <div className="inline-block animate-pulse rounded bg-zinc-100 text-transparent dark:bg-zinc-800">
        Loading views
      </div>
    )
  // If there's data, display the data
  return (
    <div className="flex items-center">
      // Mabye place an icon here?
      <span className="tabular-nums">{data?.views} views</span>
    </div>
  )
}

export default DisplayViews

In the component, we're fetching the data with the useSWR hook. We can determine if there's no data and no error either that the request ist still pending. In that case, we want to display a loading state. I put together a small component with a skeleton-like loading animation using Tailwind CSS.

If the data (or an error) arrived, we can display our final component featuring our data. Here, I am being optimistic and assume that there will be always some kind of data returned from the API. I did not set up a solution if the request only yields an error and no data.

Wrapping up

Done! Now you can use this component anywhere in your page to display view stats to a certain page slug. It even caches the API responses across your application. SWR offers you enough options to fine-tune your component. For example, you could turn off the focus revalidation and limit the revalidation to navigation events and entry visits. Happy coding!

Verifying Your Shopify Webhooks in Serverless Functions

John Schmidt — Sat, 06 Mar 2021 21:43:18 +0000

In my last post I've illustrated a basic approach to synchronize Shopify product data with your headless CMS using serverless functions. To avoid unwelcome API calls and even malicious attempts to modify your data we can use a HMAC based verification procedure provided by Shopify.

Using a secret key we can digest the request body into a HMAC hash. Comparing this to a HMAC hash provided in the request headers we can determine if the request is valid or not. Just a few modifications to our API are needed to verify the origin of received webhooks and ensure the integrity of our sync workflow.

Prerequisites

In this example I am working with serverless functions provided by Next.js built-in API routes on Vercel. Any other framework or platform deploying Node based serverless or lambda functions should work just fine as well, though. Additionally, you'll need a Shopify shop instance to get your webhooks from. You usually can create one for free as a developer. I continue to build on the example I've discussed in my last post.

You will also need a secret key to digest the request body into a HMAC hash. You can find it in the "Notification" settings of your store dashboard at the very bottom. I'd recommend storing it in an environment variable in your project to keep it safe and sound.

Raw Body Needed

In my first approach setting this up for a client, I've come across this nasty pitfall: To generate the correct HMAC digest out of the webhook request body and the secret key, we need the requests raw body. Next.js gives you the option to deactivate the default body parser. This requires that we handle the http.IncomingMessage Stream ourselves and extract the requests Buffer from within. We will use a library called raw-body to do exactly this job for us.

import getRawBody from 'raw-body'

export default async function (req, res) {
  // We need to await the Stream to rexiece the complete body Buffer
  const body = await getRawBody(req)
  // ...
}

// We turn off the default bodyParser provided by Next.js
export const config = {
  api: {
    bodyParser: false,
  },
}

Creating the HMAC Digest

Now that we got the raw body Buffer stored in a variable, we digest the raw body into a hmac hash using our secret key and compare it with the X-Shopify-Hmac-SHA256 header string in the end. Since the HMAC header is base64 encoded, we need to encode our digest as well. If the digest and the header are equal, the webhook can be deemed valid.

To create a hmac digest, Node provides us with the crypto module and its crypto.createHmac() method. We import the module into our API route and feed in the data we prepared in the previous steps. For more information on the crypto module, have a look at the official documentation.

import getRawBody from 'raw-body'
import crypto from "crypto"

export default async function (req, res) {
  // We need to await the Stream to recieve the complete body Buffer
  const body = await getRawBody(req)
  // Get the header from the request
  const hmacHeader = req.headers['x-shopify-hmac-sha256']
  // Digest the data into a hmac hash
  const digest = crypto
    .createHmac('sha256', process.env.SHOPIFY_SECRET)
    .update(body)
    .digest('base64')
  // Compare the result with the header
  if (digest === hmacHeader) {
    // VALID - continue with your tasks
    res.status(200).end()
  } else {
    // INVALID - Respond with 401 Unauthorized
    res.status(401).end()
  }
}

// We turn off the default bodyParser provided by Next.js
export const config = {
  api: {
    bodyParser: false,
  },
}

Wrapping Up

Keeping the data transfers concerning pricing and inventory safe is certainly a critical feature to headless e-commerce in general. With just a few lines of code you're able to leverage the validation built into Shopify webhook system in your serverless functions.

Keep Shopify and Your Headless CMS in Sync

John Schmidt — Thu, 11 Feb 2021 13:00:37 +0000

For one of my latest projects I had to figure a way to keep the data from my clients Shopify instance in sync with the headless CMS used for the rest of the content. In this project we were using Dato CMS as our headless CMS and Next.js as hybrid (static and server-rendered if needed) frontend. But for those of you using different products: I'd assume that you could transfer the general approach of this solution to them too.

The general idea of the content management structure was to use Shopify exclusively as the provider for the basic product data like pricing, shipping, inventory, taxes and variants. It could also provide a solid checkout solution at the end of our custom front-end flow. The content in Dato CMS builds on the basic product data and extends the possibilities. In my last project it provides additional content like nutritions, images and descriptions. It also contains all the non e-commerce content of the project. I've illustrated the basic data structure of the project below.

Prerequisites

This guide anticipates that you are working with Shopify and Dato CMS. The headless CMS might be individually exchanged if it offers some kind of content management API. In the CMS we will need a content model (sometimes referred to as type or schema) for the product to sync our Shopify data to.

Approaching the Sync

Now if we got both of our systems ready, we'd want the products from Shopify to transfer into Dato CMS and even keep synced on changes in real-time. Luckily for us, Shopify provides a webhook allowing us to receive product updates and the corresponding data in real time. We just need an endpoint for that webhook and a small piece of logic to handle the incoming data.

First, let's take a look at the data the webhook actually delivers. It depends on the type of event the webhook represents to. This is specified in a request header called x-shopify-topic. For us, the events of interest are product/create, product/update and product/delete. They represent operations in the Shopify administration. E.g., an editor hits save on an updated product and the product/update webhook fires. An example of the JSON data is illustrated below.

{
  "id": 788032119674292922,
  "title": "Example T-Shirt",
  "body_html": null,
  "vendor": "Acme",
  "product_type": "Shirts",
  "created_at": null,
  "handle": "example-t-shirt",
  "updated_at": "2021-01-07T17:09:52-05:00",
  "published_at": "2021-01-07T17:09:52-05:00",
  "template_suffix": null,
  "status": "active",
  "published_scope": "web",
  "tags": "example, mens, t-shirt",
  "admin_graphql_api_id": "gid:\/\/shopify\/Product\/788032119674292922",
  "variants": [
    {
      "id": 642667041472713922,
      "product_id": 788032119674292922,
      "title": "",
      "price": "19.99",
      "sku": "example-shirt-s",
      "position": 0,
      // ... more variant data
    },
  ],
  "images": [
    // ... image data
  ],
  "image": null
}

If the event is creation or update, the webhook sends the full product data of concern in the fashion like above. On deletion, it sends a smaller body with mainly the product's id. Now we know what data we get from Shopify. Time set up the receiving part.

Setting up API Routes in Next.js

Next.js provides a pretty straightforward way to implement API routes in our application. For this example, we create a file like api/sync.js. In that file we set up the basic async API boilerplate with our res and req objects. For demonstration purposes, I will add some comments outlining our mission ahead.

export default async (req, res) => {
  const { method, headers, body } = req
  // 0. The webhook calls from Shopify will be POST requests
  if (method === "POST") {
    // 1. Determine if the product exists in Dato CMS
    // 2. Determine the type of operation and validate it
  }
  // Catchall for invalid requests
  return res.status(400).send("Bad request")
}

Now let's start with the first few steps to prepare the processing of our data. We need to parse the incoming JSON data, determine if the product already exists in our Dato CMS project and determine the type of the operation.

Determine If the Product Exists in Dato CMS

To determine if the product already exists in our Dato CMS project, we can use the NodeJS content management client provided by the CMS itself. Add the datocms-client package to your project and construct a new client with your projects credentials.

import { SiteClient } from "datocms-client"

// You will need a read/write API token from Dato CMS
const datocms = new SiteClient(process.env.DATOCMS_API_TOKEN)

export default async (req, res) => {
  const { method, headers, body } = req
  // 0. The webhook calls from Shopify will be POST requests
  if (method === "POST") {
    // 1. Determine if the product exists in Dato CMS
    // ...
  }
  // Catchall for invalid requests
  return res.status(400).send("Bad request")
}

With the clients items.all() method we can retrieve and filter an array of our products. To determine, if the product of concern already exists we can pass any field of the content model to our method and filter the results. In my case, I've given the product model a productId field, which will contain the ID coming from Shopify, to make each product uniquely distinctive. To select the correct content model for our search, we need to pass in its model ID. It can be found in the Dato CMS administration dashboard under the models settings (image below).

Now we can pass the information we got into the client and retrieve an array of matching products.

import { SiteClient } from "datocms-client"

// You will need a read/write API token from Dato CMS
const datocms = new SiteClient(process.env.DATOCMS_API_TOKEN)

export default async (req, res) => {
  const { method, headers, body } = req
  // 0. The webhook calls from Shopify will be POST requests
  if (method === "POST") {
    // 1. Determine if the product exists in Dato CMS
    // And we destructure the first element (if found) in the filtered array
    const [existingProduct] = await datocms.items.all({
      filter: {
        // The Model ID retrieved from Dato CMS
        type: "529135",
        fields: {
          // Filter using the product ID from the webhooks data
          productId: {
            eq: String(body.id)
          }
        }
      }
    })
    // ...
  }
  // Catchall for invalid requests
  return res.status(400).send("Bad request")
}

If the product exists, the existingProduct variable would contain the desired product. If not, it will be undefined.

Determine the Desired Operation

We can now determine the desired operation based on the webhooks x-shopify-topic header and the existence of the product. First, we'll differ between case A: the product already exists and case B: the product does not exist. This also determines the specific type of operation we can execute.

import { SiteClient } from "datocms-client"

// You will need a read/write API token from Dato CMS
const datocms = new SiteClient(process.env.DATOCMS_API_TOKEN)

export default async (req, res) => {
  const { method, headers, body } = req
  // 0. The webhook calls from Shopify will be POST requests
  if (method === "POST") {
    // 1. Determine if the product exists in Dato CMS
    // And we destructure the first element (if found) in the filtered array
    const [existingProduct] = await datocms.items.all({
      filter: {
        // The Model ID retrieved from Dato CMS
        type: "529135",
        fields: {
          // Filter using the product ID from the webhooks data
          productId: {
            eq: String(body.id)
          }
        }
      }
    })
    // 2. Determine the type of operation and validate it
    // First, check if the product exists
    if (existingProduct) {
      // We can UPDATE and DELTE a product
    } else {
      // We can CREATE a product
    }
  }
  // Catchall for invalid requests
  return res.status(400).send("Bad request")
}

A simple switch block can help us to select the different possible operations within our two paths. We can specify the operations based on the existence of the product. In each case there will be a client operation (next section) and a return statement with a response status to end the API call. If the operation is not within the corresponding switch statement it will break and fallback to the response at the end.

import { SiteClient } from "datocms-client"

// You will need a read/write API token from Dato CMS
const datocms = new SiteClient(process.env.DATOCMS_API_TOKEN)

export default async (req, res) => {
  const { method, headers, body } = req
  // 0. The webhook calls from Shopify will be POST requests
  if (method === "POST") {
    // 1. Determine if the product exists in Dato CMS
    // And we destructure the first element (if found) in the filtered array
    const [existingProduct] = await datocms.items.all({
      filter: {
        // The Model ID retrieved from Dato CMS
        type: "529135",
        fields: {
          // Filter using the product ID from the webhooks data
          productId: {
            eq: String(body.id)
          }
        }
      }
    })
    // 2. Determine the type of operation and validate it
    // First, check if the product exists
    if (existingProduct) {
      // We can UPDATE and DELTE a product
      switch (headers["x-shopify-topic"]) {
        case "products/update":
          // ...
          return res.status(200).send("OK")
        case "products/delete":
          // ...
          return res.status(200).send("OK")
        default:
          // Break out of the switch if the operation is invalid
          break
      }
    } else {
      // We can CREATE a product
      switch (headers["x-shopify-topic"]) {
        case "products/create":
          // ...
          return res.status(200).send("OK")
        default:
          // Break out of the switch if the operation is invalid
          break
      }
    }
  }
  // Catchall for invalid requests
  return res.status(400).send("Bad request")
}

Performing Each Operation

The foundation is set, and we can continue to fill in the specific client operations to modify our data in Dato CMS with the client instance. There are several methods to modify items you can look up here.

Updating an item will require to specify the fields we want to update. For product creation, we will need to specify all fields our product model has. If we do not have a value for a certain field yet, we can just use null. Deletion just needs the existing items ID.

import { SiteClient } from "datocms-client"

// You will need a read/write API token from Dato CMS
const datocms = new SiteClient(process.env.DATOCMS_API_TOKEN)

export default async (req, res) => {
  const { method, headers, body } = req
  // 0. The webhook calls from Shopify will be POST requests
  if (method === "POST") {
    // 1. Determine if the product exists in Dato CMS
    // And we destructure the first element (if found) in the filtered array
    const [existingProduct] = await datocms.items.all({
      filter: {
        // The Model ID retrieved from Dato CMS
        type: "529135",
        fields: {
          // Filter using the product ID from the webhooks data
          productId: {
            eq: String(body.id)
          }
        }
      }
    })
    // 2. Determine the type of operation and validate it
    // First, check if the product exists
    if (existingProduct) {
      // We can UPDATE and DELTE a product
      switch (headers["x-shopify-topic"]) {
        case "products/update":
          await datocms.items.update(existingProduct.id, {
            // We specify the fields to update and assign the new values
            title: body.title,
            price: body.price
          })
          return res.status(200).send("OK")
        case "products/delete":
          await datocms.items.destroy(existingProduct.id)
          return res.status(200).send("OK")
        default:
          // Break out of the switch if the operation is invalid
          break
      }
    } else {
      // We can CREATE a product
      switch (headers["x-shopify-topic"]) {
        case "products/create":
          await datocms.items.create({
            // Create an item with the model ID as itemType and *ALL* fields
            itemType: "529135",
            title: body.title,
            productId: String(body.id),
            price: body.price
          })
          return res.status(200).send("OK")
        default:
          // Break out of the switch if the operation is invalid
          break
      }
    }
  }
  // Catchall for invalid requests
  return res.status(400).send("Bad request")
}

To improve debugging and the API response on exceptions we can wrap our code in a try ... catch block to properly log any errors and provide a corresponding API response.

import { SiteClient } from "datocms-client"

// You will need a read/write API token from Dato CMS
const datocms = new SiteClient(process.env.DATOCMS_API_TOKEN)

export default async (req, res) => {
  const { method, headers, body } = req
  // 0. The webhook calls from Shopify will be POST requests
  if (method === "POST") {
    try {
      // 1. Determine if the product exists in Dato CMS
      // And we destructure the first element (if found) in the filtered array
      const [existingProduct] = await datocms.items.all({
        filter: {
          // The Model ID retrieved from Dato CMS
          type: "529135",
          fields: {
            // Filter using the product ID from the webhooks data
            productId: {
              eq: String(body.id)
            }
          }
        }
      })
      // 2. Determine the type of operation and validate it
      // First, check if the product exists
      if (existingProduct) {
        // We can UPDATE and DELTE a product
        switch (headers["x-shopify-topic"]) {
          case "products/update":
            await datocms.items.update(existingProduct.id, {
              // We specify the fields to update and assign the new values
              title: body.title,
              price: body.price
            })
            return res.status(200).send("OK")
          case "products/delete":
            await datocms.items.destroy(existingProduct.id)
            return res.status(200).send("OK")
          default:
            // Break out of the switch if the operation is invalid
            break
        }
      } else {
        // We can CREATE a product
        switch (headers["x-shopify-topic"]) {
          case "products/create":
            await datocms.items.create({
              // Create an item with the model ID as itemType and *ALL* fields
              itemType: "529135",
              title: body.title,
              productId: String(body.id),
              price: body.price
            })
            return res.status(200).send("OK")
          default:
            // Break out of the switch if the operation is invalid
            break
        }
      }
    } catch (err) {
      console.error(err)
      return res.status(500).send("Internal server error")
    }
  }
  // Catchall for invalid requests
  return res.status(400).send("Bad request")
}

Testing

To test and mock the API I've used ngrok to proxy my local development server. You can send webhook test calls from the Shopify administration dashboard to your endpoint and repeat and modify the requests in your local ngrok dashboard at localhost:4040 to try out different cases.

Wrapping Up

At this point we've got a simple API that takes in data from Shopify webhooks and updates or modifies data in Dato CMS. It could certainly be enough for a small commerce project. But there's a few edge cases the API does not cover, like operations involving product variants or inventory and availability.

Shopify also provides hmac based headers in each webhook to allow verification with a secret key you can find in your Shopify dashboard. This would ensure that only trusted API calls can perform operations regarding your products and especially sensitive data like pricing.

Reach out to me on Twitter and let me know what you think about this approach and if you'd like more content about this topic.

Using Plausible Analytics in Your Next.js App

John Schmidt — Wed, 06 Jan 2021 16:44:54 +0000

I was looking for a pure, lightweight and privacy-friendly way to get simple stats about my personal homepage. I ruled out Google Analytics as they sustain little issues with privacy, and it does not fit into the mentioned attributes. So, what's out there in the market? Until this point, I've come across the following:

umami (self-hosted, open source),
Simple Analytics (paid),
Fathom Analytics (paid),
Splitbee (paid),
and Plausible (paid or self-hosted, open source)

If possible, I'd rather avoid a paid service (at least for now). Having used umami for a client project recently being quite fond of it, I've moved to Plausible, an open-source project based in the European Union, for this project. Plausible offers a pretty clean self-hosting setup via Docker. Alternatively, they offer a paid managed service on their own platform for those who prefer.

Either via plausible.io or self-hosted - after creating your site in the Plausible dashboard you're provided with a simple <script> tag looking somewhat like this:

<script
  async
  defer
  data-domain="johnschmidt.de"
  src="https://stats.johnschmidt.cloud/js/plausible.js"
/>

Of course the src and data-domain attributes might differ depending on your setup. That's all you need from Plausible itself.

Setting up Your Application

In your Next.js project we need to modify the custom document /pages/_document.js file. There's a few possible approaches to implement the tracker. In this case I implemented it manually. However, there is a small package providing you with a <PlausibleProvider> wrapper. The simplest approach is by adding the <script> tag in the <Head> component.

import Document, { Html, Head, Main, NextScript } from 'next/document'

class HomepageDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx)
    return { ...initialProps }
  }
  render() {
    return (
      <Html lang='en'>
        <Head>
          <script
            async
            defer
            data-domain='johnschmidt.de'
            src='https://stats.johnschmidt.cloud/js/plausible.js'
          />
        </Head>
        <body className='antialiased dark:bg-black dark:text-white'>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

export default HomepageDocument

In the easiest scenario this would be it - you're good to go. The script will be included into the app bundle on every page. Once deployed, the script will automatically run the tracker function and count visitors and page views. The results will be displayed in the Plausible dashboard almost instantly.

Avoiding Counts in Preview Deployments

_There's just this one little caveat: _Plausible does not differ between the domain or referring URL (yet) you call the script from. Using Vercel or Netlify for your deployments, you might use preview URLs quite frequently. A visit to one of these would trigger an event like in the production environment. As far as I was able to evaluate, there's essentially two options to avoid:

exclude yourself from tracking on the client-side or
include the script only on the desired production URL (e.g. johnschmidt.de)

The First option could be achieved with a custom rule in a script-blocking extension of sorts (e.g. uBlock, Adblock Plus). The second approach is a bit trickier at the time of writing. To avoid the <script> to render in the preview URLs we need to include the snippet conditionally, based on the current hostname. The Window object can provide this information quite simply in window.location.hostname. It'll be offered as a string. This moves the code from /pages/_document.js to /pages/_app.js since we need to check our conditions on the client-side.

import Head from 'next/head'

function HomepageApp({ Component, pageProps }) {
  return (
    <>
      <Head>
        {typeof window !== 'undefined' &&
          window.location.hostname === 'johnschmidt.de' && (
            <script
              async
              defer
              data-domain='johnschmidt.de'
              src='https://stats.johnschmidt.cloud/js/plausible.js'
            />
          )}
      </Head>
      <Component {...pageProps} />
    </>
  )
}

export default HomepageApp

Before reading the window.location.hostname parameter we need to make sure that it is only called in a client-side setting. We can check if the Window object is defined and render the script tag conditionally. Since Next.js statically generates our page on the server-side, it would try to call the Window object in a Node.js environment - albeit Window does not exist there. Once a visitor opens our app on the production URL, the script should be rendered on hydration and Plausible can start collecting your events as usual.

Wrapping up

Plausible provides a good alternative to Google Analytics, especially on the privacy side of things. The only downside is the fairly narrow adjustability within a continuous deployment environment like Vercel or Netlify. With a little tweak however, it can work like a charm. For a small project like this homepage, it seemed like one of the best solutions to get lightweight stats and baseline analytics.

Since this is my first post of this kind, let me know if this post was helpful to you and reach out to me on Twitter (@jope_sh) with feedback and ideas!