---
title: "Browser SDK"
description: "Install Tracwell's browser SDK and configure automatic page-view tracking."
documentation: "https://tracwell.app/docs/browser-sdk"
markdown: "https://tracwell.app/docs/browser-sdk.md"
---

# Browser SDK

> Install Tracwell's browser SDK and configure automatic page-view tracking.

## Install the package

### npm

```bash
npm install tracwell
```

### pnpm

```bash
pnpm add tracwell
```

### bun

```bash
bun add tracwell
```

Initialize Tracwell once in browser-only code:

```ts
import { createTracwell } from "tracwell";

const analytics = createTracwell({
  collectionMode: "private",
  projectKey: "tw_live_...",
});
```

The package is safe to import during server rendering. Call `createTracwell()` only after the document is available. Use the [framework guide](https://tracwell.app/docs/frameworks.md) for the correct mount point.

## Install with a script

```html
<script
  defer
  src="https://collect.tracwell.app/script.js"
  data-project-key="tw_live_..."
  data-collection-mode="private"
  data-consent="granted"
  data-respect-do-not-track="true"
></script>
```

The script exposes `window.tracwell` for custom events.

## Page views and routing

Tracwell records the initial page automatically. It observes `pushState`, `replaceState`, and browser back or forward navigation, covering normal path-based SPA routers.

Hash-only changes are ignored and URL fragments are excluded. Call `analytics.page()` only when the meaningful page changes without browser history changing. Do not add a router page-view hook for standard History API routing because that records duplicate page views.