npm package: @statcounter/nextjs
Description: Official Statcounter integration for Next.js
Author: Statcounter
Latest version: 0.1.5

# @statcounter/nextjs

The official [Statcounter](https://statcounter.com/) integration for Next.js.

## Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Advanced](#advanced)
- [Uninstall Steps](#uninstall-steps)
- [Support](#support)
- [Props](#props)

## Features

* **Next.js App Router Ready** : Optimized specifically for Next.js 13, 14, and 15+ using the latest `app/` directory standards.
* **Automatic Page Tracking** : Automatically records page views on client-side route changes without any manual configuration.
* **Lightweight** : Zero-dependency wrapper with minimal impact on bundle size.
* **Invisible** : Hardcoded to be hidden, ensuring your UI remains clean.
* **Easy Setup** : Very simple install process.

## Installation

Stop your server then install statcounter with this : 

```bash
npm install @statcounter/nextjs
# or
yarn add @statcounter/nextjs
```

## Usage

This package is designed for the Next.js **App Router** (Next.js 13+).

### 1. Update your Layout
Open your root layout file (usually `app/layout.tsx` or `app/layout.js`).

Import the component at the top of the file:

```tsx
import { StatCounter } from "@statcounter/nextjs";
```

### 2. Add the Component to Layout
Place the `<StatCounter />` component inside your layout just before the closing `</body>` tag.  Delete the default values for the project_id and security_code and add in the values for your project.  You can get these from the Statcounter website by clicking your project name, gear icon in the lower left corner, settings, then scroll down to bottom.

```tsx
<StatCounter project_id={1234567} security_code="abcdef12" />
```

**Example placement in your layout file.**

```tsx
// app/layout.tsx
import { StatCounter } from "@statcounter/nextjs";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Place just before closing body tag */}
        <StatCounter project_id={1234567} security_code="abcdef12" />
      </body>
    </html>
  );
}
```

### 3. Rebuild the site and restart the app
If you are developing locally, stop your server and run:

```bash
npm run dev
```

If you are deploying to production, you must rebuild to see changes:

```bash
npm run build
npm start
```

OR if you use a process manager:
```bash
pm2 restart app-name
```


### 4.  Verify install

After you rebuild the site and restart the server, go to your site and open the browser console > Network tab and reload the page.  You should see this activity in the Network tab.
Load a few different pages to make sure the counter.js fires on each page change.

```
counter.js

https://c.statcounter.com/t.php?sc_project=111111[...]
```

If your project uses Session Replay you will also see

statcounter.io
recorder.js

**Note**: If you do not see any network activity, ensure your browser Adblocker is disabled as they often block analytics scripts.

## Advanced

Instead of adding your project_id and security_code directly into the layout, you can use an environment variable if you prefer.

1.  Add your statcounter details to the .env.local file which lives in the app root folder, in the same location as the file package.json. 
If this file does not exist you can create it.

```bash
NEXT_PUBLIC_STATCOUNTER_PROJECT_ID=1234567
NEXT_PUBLIC_STATCOUNTER_SECURITY_CODE="abcabcabc"
```

2.  In your layout file use code like this in the ```<StatCounter />``` component, placing it just before the closing ```</body>``` tag.

```tsx
<StatCounter 
  project_id={Number(process.env.NEXT_PUBLIC_STATCOUNTER_PROJECT_ID || 0)} 
  security_code={process.env.NEXT_PUBLIC_STATCOUNTER_SECURITY_CODE || ""} 
/>
```

3.  Build the site and restart the app for the changes to take effect

```
npm run build
```

**Note**

The security code string in your layout file has to end with ```!``` or ``` || ""``` otherwise you will get an error like this during ```npm run build```

```tsx
Running TypeScript... Failed to compile.

./app/layout.tsx

Type error: Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

security_code={process.env.NEXT_PUBLIC_STATCOUNTER_SECURITY_CODE} />
^
```

If you setup the security code like this in the layout file it will build normally.

```tsx
process.env.NEXT_PUBLIC_STATCOUNTER_SECURITY_CODE!
```

or

```tsx
process.env.NEXT_PUBLIC_STATCOUNTER_SECURITY_CODE || ""
```

## Uninstall steps

If you want to remove Statcounter please follow these steps

### 1. Stop the server
Stop your running web app (Ctrl+C in the terminal).

### 2. Remove the package

Run this command

```bash
npm uninstall @statcounter/nextjs
# or
yarn remove @statcounter/nextjs
```

### 3. Open app/layout.tsx (or app/layout.js) and delete the following lines

Delete the import:

```tsx

import { StatCounter } from "@statcounter/nextjs";
```

Delete the component:

```tsx

<StatCounter project_id={1111111} security_code="aaaaaaa" />
```

### 4. Rebuild

Rebuild and start your app

```bash
npm run build
npm start
```

## Support

If you have any questions please email us at ![Email](https://img.shields.io/badge/support_[at]_statcounter_[dot]_com-0078d3) or use our contact form here https://statcounter.com/support/contact/

## Props

| Prop | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `project_id` | `number` | **Yes** | Your Statcounter Project ID number. |
| `security_code` | `string` | **Yes** | Your Statcounter Security Code string. |