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 @antlytics/analytics and add the <Analytics /> component from @antlytics/analytics/next in your Next.js layout.tsx. 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. Full walkthrough: Next.js App Router docs.

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 loads the hosted tracker.js via next/script with strategy="afterInteractive", so it does not block the initial page render. It handles SPA navigation by patching history.pushState / replaceState and listening for popstate.

Method 2 — Script tag (no package install)

If you prefer not to install a package, load the hosted tracker with 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
          src="https://www.antlytics.com/tracker.js"
          strategy="afterInteractive"
          data-tracking-id="your-tracking-id-uuid"
          data-api-host="https://www.antlytics.com"
        />
      </body>
    </html>
  )
}

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

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 Antlytics. 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 tracker.js or pageview. You should see the script load and 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 script-src and connect-src directives. 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 patches history.pushState / replaceState and listens for popstate. Soft navigations are counted automatically. If something still looks off, check the troubleshooting guide.

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 patches history.pushState / replaceState and listens for popstate, then 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.