npm package: @intellize/tracker
Description: Behavioral analytics for your website. One install, one line of code.
Latest version: 0.2.0

# @intellize/tracker

Behavioral analytics for production websites.

The tracker captures:

- server-side page requests
- bot traffic before it pollutes analytics
- persistent visitor and session identifiers
- client-side pageviews and SPA navigation
- clicks, rage clicks, dead clicks, and mouse movement
- scroll depth
- privacy-safe form interaction events
- JavaScript errors
- web vitals and performance telemetry
- optional session replay snapshots and DOM mutations

## Install

```bash
npm install @intellize/tracker
```

## Adapter Support

| Adapter | Server events | Client events | Notes |
| --- | --- | --- | --- |
| Express | Yes | Yes | Full support. Middleware injects the browser bundle automatically into HTML responses. |
| Next.js | Yes | Yes | Add the Next middleware and the hosted `t.js` script in your app shell. |
| Nuxt | Yes | Yes | Add the Nuxt server middleware and the hosted `t.js` script in your app shell. |
| Script tag only | No | Yes | Use when you cannot run the Node package. Bot filtering and server request tracking are unavailable. |

## Express

```ts
import express from 'express';
import { createIntelizeMiddleware } from '@intellize/tracker/express';

const app = express();

app.use(createIntelizeMiddleware({
  token: 'YOUR_SITE_ID',
}));
```

That is enough for Express. The middleware fetches remote config, records server requests, sets cookies, and injects the browser bundle before `</body>`.

## Next.js

```ts
// middleware.ts
import { createIntelizeMiddleware } from '@intellize/tracker/next';

export default createIntelizeMiddleware({
  token: 'YOUR_SITE_ID',
});
```

```tsx
// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://t.intellize.io/t.js"
        data-site="YOUR_SITE_ID"
        strategy="afterInteractive"
      />
    </html>
  );
}
```

Use the middleware for server request tracking and cookies. Add the hosted script to capture client-side events because Next middleware cannot inject HTML.

## Nuxt

```ts
// server/middleware/intellize.ts
import { defineIntelizeMiddleware } from '@intellize/tracker/nuxt';

export default defineIntelizeMiddleware({
  token: 'YOUR_SITE_ID',
});
```

```vue
<!-- app.vue -->
<script setup lang="ts">
useHead({
  script: [
    {
      src: 'https://t.intellize.io/t.js',
      defer: true,
      'data-site': 'YOUR_SITE_ID',
    },
  ],
});
</script>
```

Use the server middleware for request tracking and cookies. Add the hosted script to capture browser events because Nuxt server middleware cannot rewrite rendered HTML reliably.

## Options

```ts
createIntelizeMiddleware({
  token: 'YOUR_SITE_ID',
  configUrl: 'https://t.intellize.io',
  debug: false,
});
```

- `token`
  Required site identifier.
- `configUrl`
  Optional config host. Defaults to `https://t.intellize.io`.
- `debug`
  Optional. When `true`, logs emitted server request events to the console.

## What Gets Captured

| Event | Description |
| --- | --- |
| `request` | Server-side HTTP request with bot detection and referrer data |
| `pageview` | Initial page load and SPA navigation |
| `click` | Click target, text, and position |
| `rage_click` | Repeated clicks on the same target in a short window |
| `dead_click` | Clicks that do not appear to change the page |
| `scroll` | Scroll depth milestones |
| `form_interact` | Focus, blur, submit, and abandonment metadata without field values |
| `error` | Uncaught exceptions and unhandled rejections |
| `performance` | Browser vitals and timing metrics |
| `visibility` | Tab visibility changes |
| `mouse_move` | Sampled cursor movement for heatmaps |
| `dom_mutation` | Replay snapshots and mutation payloads when replay is enabled |

## Publishing Checklist

```bash
npm run lint
npm run build
npm run pack:check
```

## License

MIT