Getting started

Learn how to add Trackcel analytics to your React or Next.js app in five short steps. Pick your setup and every snippet on this page follows it.

Choose your setup

Select your framework and language. File names and code below update to match.

Framework
Language
Showing Next.js + TypeScript
1

Installation

Install Trackcel with your preferred package manager. It works with React and Next.js applications and ships with TypeScript types.

$ npm install trackcel

Framework support

Trackcel is optimized for React and Next.js with built-in TypeScript support. Use trackcel/next in the Next.js App Router and trackcel everywhere else (Vite, Create React App and the Pages Router).

2

Get your credentials

Every project has a public ID and a secret API key. Open your project in the dashboard and find both under Settings.

Project IDRequired
Public identifier for your project.
your-project-id
API keySecret
Secret key for authentication.
sk_live_••••••••••••

Keep your API key secure

Never commit your API key to a public repository. Use environment variables in production, and regenerate the key from project settings if it leaks.

3

Environment setup

Create an environment file to store your Trackcel credentials. The variable names differ between Next.js and React/Vite.

.env.localNEXT_PUBLIC_ prefix required
# Trackcel configuration for Next.js
NEXT_PUBLIC_TRACKCEL_PROJECT_ID=your-project-id
NEXT_PUBLIC_TRACKCEL_API_KEY=sk_live_your_api_key

# The NEXT_PUBLIC_ prefix makes these variables available in the browser.

Environment variable prefixes

Next.js requires the NEXT_PUBLIC_ prefix to make environment variables accessible in client-side code.

Security note

These variables are exposed to the browser. Never store server-side secrets with these prefixes.

Setup instructions

  1. 01Create the environment fileCreate a .env.local file in your project root, next to package.json.
  2. 02Add your credentialsCopy the variables above and replace the values with your project ID and API key.
  3. 03Restart your development serverEnvironment variables load at startup, so restart the dev server after creating the file.
4

Set up the provider

Create a provider component for Next.js + TypeScript. It reads your environment variables and starts Trackcel, so the rest of your app never has to think about it.

app/providers/analytics.tsxprocess.env
"use client";

import { Suspense } from "react";
import { NextAnalytics } from "trackcel/next";

export default function AnalyticsProvider() {
  return (
    <Suspense fallback={null}>
      <NextAnalytics
        projectId={process.env.NEXT_PUBLIC_TRACKCEL_PROJECT_ID!}
        apiKey={process.env.NEXT_PUBLIC_TRACKCEL_API_KEY!}
        debug={true}
        disableInDevelopment={true}
      />
    </Suspense>
  );
}

Environment variables

Next.js reads environment variables from process.env, and only NEXT_PUBLIC_ variables reach the browser. NextAnalytics tracks App Router navigations and needs the Suspense boundary shown above.

Configuration options

PropTypeWhat it does
projectIdrequiredstringYour project's public ID.
apiKeyrequiredstringYour secret API key.
debugbooleanEnable console logging for debugging purposes.
disableInDevelopmentbooleanDisable tracking in development (localhost and 127.0.0.1) to avoid test data.
endpointstringWhere events are sent. Defaults to https://trackcel.vercel.app; point it at your own deployment to self-host.
5

Add to your layout

Import the provider in your root layout to enable automatic page tracking across your entire application.

app/layout.tsxLayout
import AnalyticsProvider from "./providers/analytics";

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

Automatic tracking

Once added to your layout, Trackcel tracks page views, sessions, clicks, scroll depth (25, 50, 75 and 100%) and session duration across your app.

Integration comparison

FrameworkFile locationAuto routingSSR support
Next.jsApp RouterYour setupapp/layout.tsxYesYes
ReactSPAsrc/main.tsxManual*Client-side

* A React single-page app needs manual route tracking with its React Router integration.

Verify the installation

Your Next.js + TypeScript app is now set up to track visitors. Here is how to check that everything works:

  1. 1Check environment variablesMake sure .env.local is in the project root and your development server has been restarted.
  2. 2Check the browser consoleWith debug turned on, Trackcel logs each event in your browser's developer console.
  3. 3Visit your dashboardClick around your app, then open your project dashboard. Realtime shows your visit within seconds.Open dashboard
  4. 4Test page navigationMove between pages to confirm each route change adds a page view.

Common issues for Next.js + TypeScript

Environment variables are undefinedRestart your development server after creating .env.local.
Wrong prefix usedNext.js requires the NEXT_PUBLIC_ prefix for client-side variables.
File location incorrectMake sure .env.local is in your project root (same level as package.json).
Nothing shows up locallyThat is disableInDevelopment doing its job. Deploy, or set it to false while you test.
TypeScript compilation errorsMake sure your tsconfig.json includes the providers directory and your environment types are configured.

You're all set with Next.js + TypeScript.

Trackcel is configured with environment variables and tracking your Next.js application. Next, explore custom events with trackEvent(), goals and user identification.