How to Integrate Umami Analytics in Nextjs with Planetscale

I recently set up Umami analytics on my site —The one you're currently reading this post on and I believe it is a great service if you're looking to add analytics to your web app while having complete control over your data privacy for both yourself and your visitors.

In this guide, you'll learn how to integrate analytics into your nextjs application using Umami , store the data in a PlanetScale database and at the end, I'll show you how to deploy it to Vercel.

What is Umami

Umami is an open-source, privacy-focused alternative to Google Analytics that provides you with a robust analytics solution that does not violate the privacy of your users. Additionally, when you self-host Umami you are in complete control of your data.

Here's an overview of what the Umami analytics dashboard looks like:

You can also view a live demo of the Umami Docs site. Now you have an overview of what Umami looks like, let's delve into the process of integrating it into your nextjs app.

Step 1. Installation

Umami uses yarn as its package manager, so you need to first install it globally on your machine. Run the command below to install yarn:

npm install -g yarn

Next, clone the Umami repository on GitHub. You can do that quickly using the commands below:

git clone https://github.com/umami-software/umami.git

cd umami

yarn install

This will setup Umami locally and install all the required packages. Since we're self-hosting our own Umami instance, we need a database to store the data. In this post, we'll utilize PlanetScale —a MySQL-compatible serverless database platform powered by Vitess .

Step 2. Create a PlanetScale Database

• Visit PlanetScale to create an account and log in
• On the dashboard, click the "create a database" button.

• Name the database umami-db
• Select your plan type (I'm working with the entirely free hobby plan).

PlanetScale requires you to add a credit card to your account for security purposes so don't worry about adding it as you won't be charged for this process.

• On the dashboard, click Connect to create a password for your database and fill in the form with details of your project.

• Copy the .env DATABASE_URL string under the "Connect with Prisma" tab.

• Create a .env file in the root directory of the cloned Umami project and assign the URL you copied to NEXT_PUBLIC_DATABASE_URL.

Here's a snippet of what the code should look like:

# Real credentials omitted
NEXT_PUBLIC_DATABASE_URL=mysql://username:password@host/umami-db?sslaccept=strict

• Run the command below to populate the database with the schema tables.

yarn run build-db && yarn run update-db

• Once successful, visit the dashboard on PlanetScale to confirm the tables were created. You should now be able to build and start Umami locally by running the commands below:

yarn build

yarn start

Visit http://localhost:3000 to see the Umami login form. However, we won't be signing in locally, so end the server and move to the next step where we'll discuss how to deploy your Umami dashboard on Vercel.

Step 3. Deploy Umami on Vercel

Since we want to run Umami on our hosted site, we need to deploy the admin panel to a hosting service. In this case, we'll host it on Vercel but you can use other valid alternatives of your choosing.

• Create an account on Vercel .
• Click on Add a new project on the Vercel dashboard and select the Umami repository forked to your account.
• In the configure project settings, add a new Environment Variables. Set the key to DATABASE_URL and the value to the URL copied from PlanetScale.

• Hit deploy and Vercel should build your site and generate a URL you can visit to see the dashboard live.

Step 4. Connecting your Site to Umami

Visit the site URL generated by Vercel to see the login page. Use admin as the username and umami as the password.

NOTE: Make sure you change these default credentials in your profile settings to prevent unauthorized access.

Add a New Website

• Once you've logged into your account, navigate to the website tab on the top.
• On the settings panel, click the Add Website button and you should see the form to input your site details.
• Add a name field (this can be whatever you want).
• Add the Domain URL of the site you want to connect the analytics to. It should look like this: mysitename.com. This will generate a tracking code you can attach to your website.
• To get the code, click the edit button and navigate to the Tracking Code tab. Copy the script tag and move to the next section to learn how to inject this code in your app.

Step 5. Inject Tracking Code into Nextjs

In this tutorial, I'll illustrate how to inject this tracking code into a nextjs 13 application with the app router. If you're running on an older version of nextjs, check out the Script Optimization Guide to learn how you can do this in the page's route.

To inject the tracking script for all routes, import Script from next/script inside the app/layout.tsx file and include the script directly in your root layout like so:

import Script from 'next/script'
 
export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        async
        src="https://umami-victor.vercel.app/script.js"
        data-website-id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
       />
    </html>
  )
}

Once added, push these changes back to GitHub to redeploy your site. When you visit your site, Umami should start recording and delivering analytics for it.

And that's how to integrate Umami analytics into your nextjs app using PlanetScale Database and Vercel hosting. If you found value in this post, consider sharing it with friends. Looking forward to connecting with you in future posts! ⚡

Important Links

• Umami Documentation
• Umami Repository