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.
Installation
Install Trackcel with your preferred package manager. It works with React and Next.js applications and ships with TypeScript types.
$ npm install trackcelFramework 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).
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.
your-project-idsk_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.
Environment setup
Create an environment file to store your Trackcel credentials. The variable names differ between Next.js and React/Vite.
# 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
- 01Create the environment fileCreate a
.env.localfile in your project root, next topackage.json. - 02Add your credentialsCopy the variables above and replace the values with your project ID and API key.
- 03Restart your development serverEnvironment variables load at startup, so restart the dev server after creating the file.
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.
"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
| Prop | Type | What it does |
|---|---|---|
| projectIdrequired | string | Your project's public ID. |
| apiKeyrequired | string | Your secret API key. |
| debug | boolean | Enable console logging for debugging purposes. |
| disableInDevelopment | boolean | Disable tracking in development (localhost and 127.0.0.1) to avoid test data. |
| endpoint | string | Where events are sent. Defaults to https://trackcel.vercel.app; point it at your own deployment to self-host. |
Add to your layout
Import the provider in your root layout to enable automatic page tracking across your entire application.
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
| Framework | File location | Auto routing | SSR support |
|---|---|---|---|
| Next.jsApp RouterYour setup | app/layout.tsx | Yes | Yes |
| ReactSPA | src/main.tsx | Manual* | 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:
- 1Check environment variablesMake sure .env.local is in the project root and your development server has been restarted.
- 2Check the browser consoleWith debug turned on, Trackcel logs each event in your browser's developer console.
- 3Visit your dashboardClick around your app, then open your project dashboard. Realtime shows your visit within seconds.Open dashboard
- 4Test page navigationMove between pages to confirm each route change adds a page view.
Common issues for Next.js + TypeScript
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.