Next.js

Before you begin: Create your Fathom account and add your website to get its site ID. Already have one? You’re ready to follow the steps below.

Fathom Analytics works well with Next.js with minimal configuration. A huge thank you to Derrick Reimer, founder of SavvyCal for creating the incredible fathom-client package.

If you’re using Next.js App Router (v13.4+)

The App Router is the recommended approach for new Next.js applications. Here’s how to set up Fathom:

1. Install the fathom-client package:

npm install fathom-client

2. Create a Fathom component to load the tracking script. Create a new file at app/components/Fathom.tsx:

'use client';

import { load, trackPageview } from 'fathom-client';
import { useEffect, Suspense } from 'react';
import { usePathname, useSearchParams } from 'next/navigation';

function TrackPageView() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    load('YOUR-SITE-ID', {
      auto: false
    });
  }, []);

  useEffect(() => {
    if (!pathname) return;

    trackPageview({
      url: pathname + searchParams?.toString(),
      referrer: document.referrer
    });
  }, [pathname, searchParams]);

  return null;
}

export default function Fathom() {
  return (
    <Suspense fallback={null}>
      <TrackPageView />
    </Suspense>
  );
}

3. Import and use the Fathom component in your root layout (app/layout.tsx):

import Fathom from './components/Fathom';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Fathom />
        {children}
      </body>
    </html>
  );
}

For more details, see the fathom-client App Router documentation.

If you’re using Next.js Pages Router

If you’re using the Pages Router (Next.js 12 or the pages/ directory in newer versions):

Please see the fathom-client Pages Router documentation.

Tracking events

To track custom events, you can use the trackEvent function from fathom-client:

import { trackEvent } from 'fathom-client';

// Track a simple event
trackEvent('Button Clicked');

// Track an event with a value (in cents for monetary values)
trackEvent('Purchase Completed', { _value: 9900 });

Further customization

To learn about all the options we offer, read our advanced documentation here.

Ready to check your setup? Visit your published website, then open its Fathom dashboard to check for your first pageview. If it doesn’t appear, our installation troubleshooting guide will help.