Next.js Quick Start

This guide covers both the App Router (Next.js 13+) and Pages Router (Next.js 12 and earlier).

Install the Package

npm

npm install @grainql/tag

yarn

yarn add @grainql/tag

pnpm

pnpm add @grainql/tag

App Router (Next.js 13+)

Create an Analytics Component

Grain Tag must be initialized on the client. Create a client component that runs once:

// app/grain.tsx
'use client';

import { useEffect } from 'react';
import { init, isInitialized } from '@grainql/tag';

export function GrainAnalytics() {
  useEffect(() => {
    if (!isInitialized()) {
      init({ tenantId: process.env.NEXT_PUBLIC_GRAIN_TENANT_ID! });
    }
  }, []);
  return null;
}

Add to Your Root Layout

// app/layout.tsx
import { GrainAnalytics } from './grain';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <GrainAnalytics />
        {children}
      </body>
    </html>
  );
}

Add Environment Variable

Create a .env.local file:

NEXT_PUBLIC_GRAIN_TENANT_ID=your-tenant-id

Replace your-tenant-id with the alias from your dashboard.

Use in Components

Now you can track events from any Client Component:

// app/page.tsx
'use client';

import { track } from '@grainql/tag';

export default function HomePage() {
  return (
    <div>
      <h1>Welcome!</h1>
      <button onClick={() => track('cta_clicked', { location: 'hero' })}>
        Get Started
      </button>
    </div>
  );
}

Server vs Client Components: track(), identify(), and other Grain Tag functions must be called from Client Components (with the 'use client' directive) or inside useEffect. Grain Tag is SSR safe — init() returns a no-op in non-browser environments — but tracking functions need the browser to work.

Automatic page views: Grain Tag hooks into the History API to track page views and navigation automatically. You do not need a page view tracker component — this works out of the box with Next.js App Router.

Identify Users

// Any client component
'use client';

import { identify, track } from '@grainql/tag';

export function LoginHandler() {
  const handleLogin = async (email: string, password: string) => {
    const user = await yourLoginFunction(email, password);
    identify(user.id);
    track('user_logged_in', { method: 'email' });
  };

  return <form onSubmit={handleLogin}>...</form>;
}

'use client';

import { getInstance } from '@grainql/tag';

export function ConsentBanner() {
  const handleAccept = () => {
    const grain = getInstance();
    grain?.consent.grant();
  };

  const handleDecline = () => {
    const grain = getInstance();
    grain?.consent.revoke();
  };

  return (
    <div>
      <p>We use analytics to improve your experience.</p>
      <button onClick={handleAccept}>Accept</button>
      <button onClick={handleDecline}>Decline</button>
    </div>
  );
}

Pages Router (Next.js 12)

Initialize in _app.tsx

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect } from 'react';
import { init, isInitialized } from '@grainql/tag';

export default function App({ Component, pageProps }: AppProps) {
  useEffect(() => {
    if (!isInitialized()) {
      init({ tenantId: process.env.NEXT_PUBLIC_GRAIN_TENANT_ID! });
    }
  }, []);

  return <Component {...pageProps} />;
}

Add Environment Variable

Create a .env.local file:

NEXT_PUBLIC_GRAIN_TENANT_ID=your-tenant-id

Use in Pages

// pages/index.tsx
import { track } from '@grainql/tag';

export default function HomePage() {
  return (
    <div>
      <h1>Welcome!</h1>
      <button onClick={() => track('cta_clicked', { location: 'hero' })}>
        Get Started
      </button>
    </div>
  );
}

Automatic page views: Grain Tag automatically tracks navigation via the History API for both App Router and Pages Router. No manual page view tracking is needed.

Server-Side Tracking

For tracking events from API routes or Server Actions, use @grainql/analytics-web (a different package designed for server-side use):

npm install @grainql/analytics-web

API Routes

// app/api/checkout/route.ts (App Router)
// Server-side tracking uses @grainql/analytics-web (a different package)
import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

export async function POST(request: Request) {
  const body = await request.json();

  // Track server-side event
  await grain.track('checkout_completed', {
    order_id: body.orderId,
    total: body.total
  }, { flush: true }); // Flush immediately for serverless

  return Response.json({ success: true });
}

Serverless tip: Use { flush: true } to send events immediately before the function terminates.

Server Actions (App Router)

// app/actions.ts
'use server';

// Server-side tracking uses @grainql/analytics-web (a different package)
import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

export async function submitForm(formData: FormData) {
  // Your form logic...

  await grain.track('form_submitted', {
    form_name: 'contact'
  }, { flush: true });

  return { success: true };
}

What’s Next?

Core API Reference

See all available methods and options

User Identification

Track users across sessions

Event Best Practices

Learn what to track and how to structure events

Server-Side Setup

Advanced server-side configuration

Vercel deployment: All environment variables starting with NEXT_PUBLIC_ are automatically available in the browser. Keep secret keys (for server-side tracking) private by omitting the NEXT_PUBLIC_ prefix.

Need remote configuration or feature flags? See @grainql/analytics-web for remote config, React hooks (useConfig, useTrack, GrainProvider), and more.

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

Install the Package

App Router (Next.js 13+)

Create an Analytics Component

Add to Your Root Layout

Add Environment Variable

Use in Components

Identify Users

Pages Router (Next.js 12)

Initialize in _app.tsx

Add Environment Variable

Use in Pages

Server-Side Tracking

API Routes

Server Actions (App Router)

What’s Next?

Core API Reference

User Identification

Event Best Practices

Server-Side Setup

​Install the Package

​App Router (Next.js 13+)

​Create an Analytics Component

​Add to Your Root Layout

​Add Environment Variable

​Use in Components

​Identify Users

​Consent Management

​Pages Router (Next.js 12)

​Initialize in _app.tsx

​Add Environment Variable

​Use in Pages

​Server-Side Tracking

​API Routes

​Server Actions (App Router)

​What’s Next?

Core API Reference

User Identification

Event Best Practices

Server-Side Setup

Install the Package

App Router (Next.js 13+)

Create an Analytics Component

Add to Your Root Layout

Add Environment Variable

Use in Components

Identify Users

Consent Management

Pages Router (Next.js 12)

Initialize in _app.tsx

Add Environment Variable

Use in Pages

Server-Side Tracking

API Routes

Server Actions (App Router)

What’s Next?