Install Walityk on Next.js

This guide covers installing Walityk in a Next.js app, App Router (15+) or Pages Router (12+). Plan for 15 minutes.

1. Install the SDK

pnpm add @walityk/next
# or npm install @walityk/next / yarn add @walityk/next

2. Configure your site key

Grab your key from the Walityk dashboard (Sites → New site → Next.js), then add to .env.local:

NEXT_PUBLIC_WALITYK_SITE_KEY=wlk_live_xxxxxxxxxxxxx
WALITYK_SERVER_KEY=wlk_srv_xxxxxxxxxxxxx

The SITE_KEY is public (used client-side for page_view). The SERVER_KEY is secret: it signs server-side events and must never be exposed to the browser.

3. App Router — root provider

In app/layout.tsx:

import { WalitykProvider } from '@walityk/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <WalitykProvider siteKey={process.env.NEXT_PUBLIC_WALITYK_SITE_KEY!}>
          {children}
        </WalitykProvider>
      </body>
    </html>
  );
}

page_view events are sent automatically on every navigation (router events).

Pages Router (alternative)

In pages/_app.tsx:

import { WalitykProvider } from '@walityk/next';

export default function App({ Component, pageProps }) {
  return (
    <WalitykProvider siteKey={process.env.NEXT_PUBLIC_WALITYK_SITE_KEY!}>
      <Component {...pageProps} />
    </WalitykProvider>
  );
}

4. Track a client event

'use client';
import { useWalityk } from '@walityk/next';

export function SignupButton() {
  const { track } = useWalityk();
  return (
    <button onClick={() => track('signup_clicked', { plan: 'starter' })}>
      Sign up
    </button>
  );
}

5. Track a server-side event

For critical conversions (purchase, confirmed signup), send the event from your Route Handler or Server Action:

// app/api/checkout/route.ts
import { walityk } from '@walityk/next/server';

export async function POST(req: Request) {
  const { orderId, amount, email } = await req.json();
  await walityk.track('purchase', {
    value: amount,
    currency: 'EUR',
    transaction_id: orderId,
    user: { email },
  }, { request: req });
  return Response.json({ ok: true });
}

The server SDK reads WALITYK_SERVER_KEY from process.env automatically. It hashes PII (email, phone) before sending.

6. Verify

Open Live debug in the Walityk dashboard, browse your local app and trigger a conversion. Events appear in real time.

Best practices

✅ Server-side first for monetary conversions (purchase, subscribe).
✅ Client-side only for behavior (click, scroll, page_view).
✅ Use headers() server-side to read the _wlk cookie that links client/server sessions.
❌ Never log SERVER_KEY client-side (NEXT_PUBLIC_* is public!).

What’s next?

Connect your destinations (GA4, Meta, Google Ads) from the dashboard.
Read the Edge runtime guide if you deploy to Vercel Edge or Cloudflare Workers.

Need help? hi@walityk.com.