Progress:

Installation

Getting Started

Learn how to integrate Trackcel analytics into your React or Next.js application in just a few simple steps.

Choose your setup:

Select your framework and language preference. All code examples will be customized for your choice.

Framework

Language

Current selection:Next.js + TypeScript

Installation

Install Trackcel using your preferred package manager. Trackcel works seamlessly with React and Next.js applications.

Select package manager:

Current: npm

Terminal

$ npm install trackcel

Framework Support: Trackcel is optimized for React and Next.js applications with built-in TypeScript support.

Get Your Credentials

Navigate to your project dashboard to generate the required credentials for your application.

Project ID

Public identifier for your project

Required

cm8j08uk40304tf4wd33yy07m

API Key

Secret key for authentication

Secret

••••••••••••••••••••••••••••••••

Keep your API key secure: Never expose your API key in client-side code or public repositories. Use environment variables in production.

Environment Setup

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

Environment File for Next.js + TypeScript

NEXT_PUBLIC_ prefix required

.env.localenv

# Trackcel Configuration for Next.js
NEXT_PUBLIC_TRACKCEL_PROJECT_ID=cm8j08uk40304tf4wd33yy07m
NEXT_PUBLIC_TRACKCEL_API_KEY=sk_live_875c2bdf439b42b58ab52b8b4175c8c3

# Note: NEXT_PUBLIC_ prefix makes these variables available in the browser
# Only use this for public credentials that are safe to expose client-side

Environment Variable Prefixes: Next.js requires NEXT_PUBLIC_ prefix to make environment variables accessible in client-side code.

Security Note: These environment variables will be exposed to the client-side. Only use public/safe credentials here. Never store server-side secrets with these prefixes.

Setup Instructions:

Create the environment file

Create a .env.local file in your project root directory

Add your credentials

Copy the environment variables from above and replace the values with your actual credentials

Restart your development server

Environment variables are loaded at startup, so restart your dev server after creating the file

Create Analytics Provider

Create a provider component for Next.js + TypeScript. This component reads from environment variables and initializes Trackcel analytics.

Provider Component for Next.js + TypeScript

process.env

.tsx

providers/analytics.tsxTypeScript

"use client";

import { Analytics } from "trackcel";

export default function AnalyticsProvider(): JSX.Element {
  return (
    <Analytics
      projectId={process.env.NEXT_PUBLIC_TRACKCEL_PROJECT_ID!}
      apiKey={process.env.NEXT_PUBLIC_TRACKCEL_API_KEY!}
      debug={true}
      disableInDevelopment={true}
    />
  );
}

ℹ️

Environment Variables: Next.js uses process.env to access environment variables with NEXT_PUBLIC_ prefix for client-side access.

Configuration Options

debug

Enable console logging for debugging purposes

boolean

disableInDevelopment

Disable tracking in development mode to avoid test data

boolean

Add to Your Layout

Import and add your analytics provider to your root layout to enable automatic page tracking across your entire application.

Integration for Next.js + TypeScript

Layout

.tsx

app/layout.tsxTypeScript

import AnalyticsProvider from "./providers/analytics";

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

Automatic Tracking: Once added to your layout, Trackcel will automatically track page views, user sessions, and basic interactions across your entire application.

Integration Comparison

Framework	File Location	Auto Routing	SSR Support
Next.jsApp Router	`app/layout.tsx`
ReactSPA	`src/main.tsx`	Manual*	Client-side

* React SPA requires manual route tracking with React Router integration

✓

Verify Installation

Your Next.js + TypeScript application is now configured to track visitor data. Here's how to verify everything is working correctly:

Check Environment Variables

Ensure your .env.local file is in the project root and your development server has been restarted.

Check Browser Console

With debug mode enabled, you should see Trackcel logs in your browser's developer console.

Visit Your Dashboard

Navigate through your application, then check your project dashboard for real-time analytics data.

Test Page Navigation

Navigate between different pages to ensure automatic page view tracking is working.

Common Issues for Next.js + TypeScript:

Environment variables undefined:Make sure to restart your development server after creating .env.local

Wrong prefix used:Next.js requires NEXT_PUBLIC_ prefix for client-side variables

File location incorrect:Ensure .env.local is in your project root directory (same level as package.json)

TypeScript compilation errors:Ensure your tsconfig.json includes the providers directory and environment types are properly configured

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

Trackcel is now securely configured with environment variables and tracking your Next.js application.

Next steps: Explore advanced tracking features, custom events, and user identification in the documentation.