How to Add Microsoft Clarity to Next.js 14 with App Router

51 min read

Introduction

Microsoft Clarity is a powerful analytics tool that provides heatmaps, session recordings, and other valuable insights into how users interact with your website. In this guide, we'll walk through the process of adding Microsoft Clarity to a Next.js 14 application using the new App Router architecture.

Prerequisites

  • A Next.js 14 project using the App Router
  • A Microsoft Clarity account and tracking code
  • Basic understanding of Next.js and React

Implementation Steps

1. Get Your Clarity Tracking Code

First, you'll need to get your Clarity tracking code from the Microsoft Clarity dashboard. It typically looks like this:

(function(c,l,a,r,i,t,y){
    c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
    t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
    y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "your-clarity-id");

2. Add Script to Root Layout

In your Next.js 14 project, locate or create the root layout file at app/layout.js (or layout.tsx). This is where we'll add the Clarity tracking script.

Here's the complete implementation:

import { Inter } from 'next/font/google'
import Script from 'next/script'

const inter = Inter({ subsets: ['latin'] })

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <Script id="microsoft-clarity" strategy="afterInteractive">
          {`
            (function(c,l,a,r,i,t,y){
                c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
                t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
                y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
            })(window, document, "clarity", "script", "your-clarity-id");
          `}
        </Script>
      </head>
      <body className={inter.className}>{children}</body>
    </html>
  )
}

3. Understanding the Implementation

Let's break down the key elements of this implementation:

Using next/script Component

We use the Script component from next/script instead of a regular <script> tag because it provides several benefits:

  • Better performance optimization
  • Automatic resource loading management
  • Built-in error handling

Script Strategy

The strategy="afterInteractive" prop tells Next.js to load the script after the page becomes interactive. This is important for:

  • Optimizing page load performance
  • Ensuring accurate tracking
  • Not blocking the initial page render

Best Practices and Considerations

1. Privacy Compliance

When implementing analytics tools like Clarity, ensure you:

  • Update your privacy policy to include information about session recording
  • Implement proper cookie consent mechanisms if required
  • Follow GDPR, CCPA, and other relevant privacy regulations

2. Performance Optimization

The next/script component automatically:

  • Defers script loading appropriately
  • Manages script execution timing
  • Prevents render-blocking behavior

3. Error Handling

While Clarity's script is generally reliable, it's good practice to:

  • Monitor the console for any potential errors
  • Ensure the script doesn't interfere with your application's functionality
  • Test the implementation across different pages and user flows

Conclusion

Adding Microsoft Clarity to a Next.js 14 application using the App Router is straightforward when using the next/script component. This implementation ensures that your analytics tracking is both performant and reliable while following Next.js best practices.

Remember to replace your-clarity-id with your actual Microsoft Clarity tracking ID before deploying your application.

Resources