Install on Next.js

Add Loomduct to a Next.js App Router app.

Add Loomduct to a Next.js app that uses the App Router. Page views are tracked from the first page, and on every client-side navigation.

Install with your AI agent

Add Loomduct analytics to this project. Follow the steps in https://loomduct.com/docs/install/ai-agent.md Ask me for the project token. Do not read .env files.

Before you start

A Loomduct project and its project token. In the dashboard, open the project menu, select Project settings, then Copy project token.
Next.js 15.3 or newer, which runs instrumentation-client.ts in the browser.

Steps

Install the package

npm install @loomduct/js

Add the token to your environment

.env.local

NEXT_PUBLIC_LOOMDUCT_TOKEN=lmt_your_project_token

Next.js puts variables that start with NEXT_PUBLIC_ into the browser bundle. The token is public, so this is fine.

Create one instance

lib/loomduct.ts

import { Loomduct } from '@loomduct/js'
import { webAnalytics } from '@loomduct/js/web-analytics'

export const loomduct = new Loomduct({
  token: process.env.NEXT_PUBLIC_LOOMDUCT_TOKEN!,
  plugins: [webAnalytics()],
})

You can import this file from server code too. Creating the instance has no side effects, and load() does nothing on the server.

Load it in instrumentation-client.ts

Create instrumentation-client.ts in the root of your project, next to app/:

instrumentation-client.ts

import { loomduct } from './lib/loomduct'

loomduct.load()

Next.js runs this file in the browser before your app starts, so the first page view is tracked.

Track events from client components

app/signup-button.tsx

'use client'

import { loomduct } from '@/lib/loomduct'

export function SignupButton() {
  return (
    <button onClick={() => loomduct.track('signup_clicked')}>Sign up</button>
  )
}

Check that it worked

Deploy the app and open it in a new tab. Loomduct skips localhost; to test with next dev, add allowLocalhost: true to the options for a moment.
Open your project in the dashboard. Your visit shows up as online now on the Overview.
Select a link to another page of your app. A second page view shows up.