---
title: "Next.js | Installation | Documentation - Vemetric"
description: "Easily integrate Vemetric into your Next.js application."
url: https://vemetric.com/docs/installation/nextjs
---

# Integrate Vemetric into your Next.js application

Easily integrate Vemetric into your Next.js application.

* * *

Next.js is a powerful React framework that supports both client-side and server-side rendering. With its evolving architecture, you have multiple options for integrating Vemetric depending on your Next.js version and use case.

This guide covers all integration methods, helping you choose the right approach for your Next.js application.

## Client-Side Setup

Client-side tracking captures user interactions in the browser, including page views, custom events, and outbound link clicks.

**Next.js 15.3+**

Next.js 15.3 introduced the `instrumentation-client.ts` file, which runs on the client before any other code. This works with both App Router and Pages Router.

### Install the JavaScript SDK

In your project directory, run:

```bash
npm install @vemetric/web
```

> We use `@vemetric/web` here because `instrumentation-client.ts` runs before React initializes.

### Create instrumentation-client.ts

Create a file called `instrumentation-client.ts` in your project root (same level as the `app` or `pages` directory):

```ts
import { vemetric } from '@vemetric/web';

vemetric.init({
  token: process.env.NEXT_PUBLIC_VEMETRIC_TOKEN!,
});
```

See the [JavaScript SDK docs](https://vemetric.com/docs/sdks/javascript#configuration) for detailed explanations of each option.

> Make sure to set the `NEXT_PUBLIC_VEMETRIC_TOKEN` environment variable with your project token (found in the project settings).

### Verify installation

Once added, Vemetric will automatically start tracking page views. You can verify this by checking your Vemetric dashboard for incoming events a few seconds after loading a page.

> Data from `localhost` won’t be tracked by default.

### Optional: Track custom events and identify logged-in users

You can track custom events from any Client Component by importing the `vemetric` object:

```tsx
'use client';

import { vemetric } from '@vemetric/web';

export function MyComponent() {
  return (
    <button onClick={() => vemetric.trackEvent('button_clicked')}>
      Click me
    </button>
  );
}
```

See the [JavaScript SDK docs](https://vemetric.com/docs/sdks/javascript#trackevent) for a detailed explanation of the available parameters.

Also learn more about [User Identification](https://vemetric.com/docs/product-analytics/user-identification) to track authenticated users and see their [full journey](https://vemetric.com/docs/product-analytics/user-journeys).

**Next.js 15.2 and below**

For Next.js apps on version 15.2 and below, initialize Vemetric in your root layout or app file.

**App Router**

### Install the React SDK

In your project directory, run:

```bash
npm install @vemetric/react
```

### Initialize in layout.tsx

Import and include the `VemetricScript` component in your root `layout.tsx` file:

```tsx
import { VemetricScript } from '@vemetric/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <VemetricScript token={process.env.NEXT_PUBLIC_VEMETRIC_TOKEN!} />
        {children}
      </body>
    </html>
  );
}
```

See the [React SDK docs](https://vemetric.com/docs/sdks/react#configuration) for detailed explanations of each option.

> Make sure to set the `NEXT_PUBLIC_VEMETRIC_TOKEN` environment variable with your project token (found in the project settings).

### Verify installation

Once added, Vemetric will automatically start tracking page views. You can verify this by checking your Vemetric dashboard for incoming events a few seconds after loading a page.

> Data from `localhost` won’t be tracked by default.

### Optional: Track custom events and identify logged-in users

You can track custom events from any Client Component by importing the `vemetric` object:

```tsx
'use client';

import { vemetric } from '@vemetric/react';

export function MyComponent() {
  return (
    <button onClick={() => vemetric.trackEvent('button_clicked')}>
      Click me
    </button>
  );
}
```

See the [React SDK docs](https://vemetric.com/docs/sdks/react#trackevent) for a detailed explanation of the available parameters.

Also learn more about [User Identification](https://vemetric.com/docs/product-analytics/user-identification) to track authenticated users and see their [full journey](https://vemetric.com/docs/product-analytics/user-journeys).

**Pages Router**

### Install the React SDK

In your project directory, run:

```bash
npm install @vemetric/react
```

### Initialize in \_app.tsx

Import and include the `VemetricScript` component in your `_app.tsx` file:

```tsx
import type { AppProps } from 'next/app';
import { VemetricScript } from '@vemetric/react';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <VemetricScript token={process.env.NEXT_PUBLIC_VEMETRIC_TOKEN!} />
      <Component {...pageProps} />
    </>
  );
}
```

See the [React SDK docs](https://vemetric.com/docs/sdks/react#configuration) for detailed explanations of each option.

> Make sure to set the `NEXT_PUBLIC_VEMETRIC_TOKEN` environment variable with your project token (found in the project settings).

### Verify installation

Once added, Vemetric will automatically start tracking page views. You can verify this by checking your Vemetric dashboard for incoming events a few seconds after loading a page.

> Data from `localhost` won’t be tracked by default.

### Optional: Track custom events and identify logged-in users

You can track custom events from any Component by importing the `vemetric` object:

```tsx
import { vemetric } from '@vemetric/react';

export function MyComponent() {
  return (
    <button onClick={() => vemetric.trackEvent('button_clicked')}>
      Click me
    </button>
  );
}
```

See the [React SDK docs](https://vemetric.com/docs/sdks/react#trackevent) for a detailed explanation of the available parameters.

Also learn more about [User Identification](https://vemetric.com/docs/product-analytics/user-identification) to track authenticated users and see their [full journey](https://vemetric.com/docs/product-analytics/user-journeys).

## Server-Side Setup

Server-side tracking is useful for tracking backend events like purchases, sign-ups, or other important conversions that happen on the server.

> Server-side tracking complements client-side tracking but doesn’t track page views. Use `@vemetric/node` in addition to client-side tracking, not as a replacement.

**App Router**

### Install the Node.js SDK

```bash
npm install @vemetric/node
```

### Create a shared client

Create a file like `lib/vemetric.ts` to store your Vemetric client:

```ts
import { Vemetric } from '@vemetric/node';

export const vemetric = new Vemetric({
  token: process.env.NEXT_PUBLIC_VEMETRIC_TOKEN!,
});
```

> It’s fine to use the same `NEXT_PUBLIC_VEMETRIC_TOKEN` environment variable as your client-side code.

### Use in Server Components, Actions, and Routes

Import and use the `vemetric` client anywhere on the server:

**Server Component:**

```tsx
import { vemetric } from '@/lib/vemetric';

export default async function Dashboard() {
  await vemetric.trackEvent('DashboardViewed', {
    userIdentifier: 'user-123',
    userDisplayName: 'John Doe',
  });

  return <div>Dashboard</div>;
}
```

**Server Action:**

```tsx
'use server';

import { vemetric } from '@/lib/vemetric';

export async function handlePurchase(userId: string) {
  await vemetric.trackEvent('PurchaseCompleted', {
    userIdentifier: userId,
    eventData: { amount: 99.99, currency: 'USD' },
  });
}
```

**Route Handler `app/api/data/route.ts`:**

```tsx
import { vemetric } from '@/lib/vemetric';

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

  await vemetric.trackEvent('ApiCalled', {
    userIdentifier: data.userId,
    eventData: { endpoint: '/api/data' },
  });

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

**Pages Router**

### Install the Node.js SDK

```bash
npm install @vemetric/node
```

### Create a shared client

Create a file like `lib/vemetric.ts` to store your Vemetric client:

```ts
import { Vemetric } from '@vemetric/node';

export const vemetric = new Vemetric({
  token: process.env.NEXT_PUBLIC_VEMETRIC_TOKEN!,
});
```

> It’s fine to use the same `NEXT_PUBLIC_VEMETRIC_TOKEN` environment variable as your client-side code.

### Use in API routes and getServerSideProps

**API Route `pages/api/purchase.ts`:**

```tsx
import type { NextApiRequest, NextApiResponse } from 'next';
import { vemetric } from '@/lib/vemetric';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'POST') {
    await vemetric.trackEvent('PurchaseCompleted', {
      userIdentifier: req.body.userId,
      eventData: { amount: req.body.amount },
    });

    res.status(200).json({ success: true });
  }
}
```

**getServerSideProps:**

```tsx
import { vemetric } from '@/lib/vemetric';
import type { GetServerSideProps } from 'next';

export const getServerSideProps: GetServerSideProps = async (context) => {
  // Track server-side page view
  await vemetric.trackEvent('TriggerRerender', {
    userIdentifier: context.req.cookies.userId,
  });

  return { props: {} };
};
```

See the [Node.js SDK docs](https://vemetric.com/docs/sdks/nodejs) for all available methods and options.

## Related Resources

> We highly recommend you to use a custom proxy in front of Vemetric for better results. See our guide on [setting up a custom proxy with Next.js](https://vemetric.com/docs/advanced-guides/using-a-proxy/nextjs) for more information.

Also keep in mind that one project can be used to track data from multiple websites or applications. See our guide on [tracking across subdomains](https://vemetric.com/docs/advanced-guides/track-across-subdomains) for more information.