How to Set Up Antlytics on Next.js (Step by Step)

Three methods, one goal: privacy-friendly analytics running on your Next.js site. Start with the SDK for the fastest path. Add the first-party proxy if you want analytics requests to survive ad blockers.

Key idea: Install the @antlytics/analytics SDK in your Next.js layout.tsx with one import and one component. Add the first-party proxy if you want analytics requests to bypass ad blockers.

Prerequisites

Next.js 13 or later with App Router
An Antlytics account (Free tier works — sign up here)
Your tracking ID from Settings → Tracking Snippet in the dashboard

Method 1 — SDK component (recommended)

The SDK is the recommended approach for Next.js. It handles App Router, SPA navigation, and the first-party proxy configuration cleanly.

Step 1: Install the package

npm install @antlytics/analytics
# or
pnpm add @antlytics/analytics

Step 2: Add the component to your root layout

// app/layout.tsx
import { Analytics } from "@antlytics/analytics/next"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Analytics
          trackingId="your-tracking-id-uuid"
          apiHost="https://www.antlytics.com"
        />
      </body>
    </html>
  )
}

The apiHost defaults to https://www.antlytics.com — you only need to specify it if you are using the first-party proxy (Method 3 below).

The SDK component renders an inline script using next/script with strategy="afterInteractive", so it does not block the initial page render. It handles SPA navigation by listening for popstate events.

Method 2 — Script tag (no package install)

If you prefer not to install a package, use the tracking snippet from your dashboard directly in layout.tsx via next/script:

// app/layout.tsx
import Script from "next/script"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          id="antlytics"
          strategy="afterInteractive"
          dangerouslySetInnerHTML={{
            __html: `(function(){
  var t="your-tracking-id-uuid",
      u="https://www.antlytics.com/api/ingest/pageview",
      k="ant_sid";
  function sid(){
    try{var s=sessionStorage.getItem(k);if(s)return s;
    s=crypto.randomUUID();sessionStorage.setItem(k,s);return s;}
    catch(e){return crypto.randomUUID();}
  }
  function send(){
    var p=location.pathname,q=location.search;
    var utm={};
    ["utm_source","utm_medium","utm_campaign","utm_content","utm_term"].forEach(function(k){
      var v=new URLSearchParams(q).get(k);if(v)utm[k]=v;
    });
    fetch(u,{method:"POST",headers:{"Content-Type":"application/json"},
    keepalive:true,body:JSON.stringify(Object.assign(
      {tracking_id:t,pathname:p,referrer:document.referrer||undefined,session_id:sid()},
      utm
    ))}).catch(function(){});
  }
  send();
  window.addEventListener("popstate",send);
})();`
          }}
        />
      </body>
    </html>
  )
}

Copy the exact snippet from your dashboard rather than typing it manually — the dashboard generates it with your tracking ID pre-filled.

Method 3 — First-party proxy

The first-party proxy routes analytics requests through your own domain. Ad blockers block requests to known analytics hostnames; they cannot block requests to your own domain.

Step 1: Create the proxy route handler

// app/api/antlytics/pageview/route.ts
export { GET, OPTIONS, POST } from "@antlytics/analytics/proxy"

Step 2: Configure the SDK to use your domain

<Analytics
  trackingId="your-tracking-id-uuid"
  apiHost="https://your-domain.com"
/>

When apiHost is set to your domain, the SDK sends pageview requests to /api/antlytics/pageview on your domain. The proxy route forwards them to https://www.antlytics.com/api/ingest/pageview. Ad blockers see only a request to your own domain.

For detailed proxy documentation, see first-party proxy docs.

Verifying it works

Open your site in a browser with no ad-blocker extensions.
Open the browser developer tools, go to the Network tab.
Filter by pageview. You should see a successful POST request to the Antlytics ingest endpoint (or your proxy route if you're using Method 3).
Open your Antlytics dashboard. You should see a real-time visitor within a few seconds.

If you do not see data in the dashboard, work through the troubleshooting guide.

Setting up your first conversion goal

A conversion goal measures how many sessions reach an important page. In Antlytics, goals are path-based: when a session includes a pageview at the specified pathname, the goal is counted.

Go to Settings → Goals in your Antlytics dashboard.
Enter the pathname you want to track (for example /thank-you or /signup/success).
Save. The goal appears in your dashboard overview for the currently selected site.

For full goal configuration options, see conversion goals.

Troubleshooting

Script not firing (CSP headers) — If your Content Security Policy blocks external scripts or fetch requests, add https://www.antlytics.com to your connect-src directive. If using the first-party proxy, only your own domain needs to be in connect-src.

Wrong tracking ID — Double-check the tracking ID in your layout.tsx matches the ID shown in your Antlytics dashboard under Settings → Tracking Snippet. The ID is a UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

SPA navigation not tracked — The Antlytics tracker listens for popstate events. If your router uses a mechanism that does not trigger popstate (rare), the SDK may need explicit re-firing. Check the troubleshooting guide for details.

Ad blocker blocking requests — Use an incognito window or a browser without ad-blocker extensions to test. For production accuracy, set up the first-party proxy.

Edge Runtime compatibility — The proxy route handler should use the default Node.js runtime, not Edge Runtime. Do not add export const runtime = "edge" to the proxy route file.

FAQ

Does this work with the Pages Router? The SDK component works in both App Router and Pages Router. For Pages Router, add it to _app.tsx instead of layout.tsx.

Do I need the proxy? Not required. Start without it and add later if ad-blocker accuracy matters for your site.

How does Antlytics handle client-side navigation? The tracker listens for popstate events and re-fires on each navigation. The SDK handles this automatically.

Will this slow down my site? The tracker is lightweight and loads with strategy="afterInteractive", so it is not in the critical rendering path. In typical Next.js setups this has negligible impact on Core Web Vitals — use Lighthouse before and after installation to confirm for your specific site.

What if I'm using Turbopack? No impact. The SDK is a standard React component and is not affected by the bundler.