# @woocommerce/tracks

> WooCommerce user event tracking utilities for Automattic based projects.

Latest version **1.5.1** (published 2026-06-11) · GPL-2.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @woocommerce/tracks
pnpm add @woocommerce/tracks
yarn add @woocommerce/tracks
bun add @woocommerce/tracks
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.5.1 |
| Published | 2026-06-11 |
| First published | 2020-09-11 |
| Weekly downloads | 0 |
| License | GPL-2.0-or-later |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^24.15.0 |
| Dependencies | 1 |
| Unpacked size | 19.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 10508 |
| Author | Automattic |
| Maintainers | mikejolley, albertjuhe, nerrad, obliviousharmony, louwie17, chihsuan, ~woocommerce, zhongruige, opr, kraftbj |
| Keywords | wordpress, woocommerce, tracks |

## Links

- npm: https://www.npmjs.com/package/@woocommerce/tracks
- Repository: https://github.com/woocommerce/woocommerce
- Homepage: https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/tracks/README.md
- Issues: https://github.com/woocommerce/woocommerce/issues
- npm.io page: https://npm.io/package/@woocommerce/tracks

## Dependencies (1)

- [debug](https://npm.io/package/debug.md) ^4.3.4

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 1.5.1 (latest) — 2026-06-11
- 1.5.0 — 2026-02-23
- 1.4.0 — 2024-06-11
- 1.3.0 — 2022-07-08
- 1.2.0 — 2022-06-15
- 1.1.1 — 2022-03-23
- 1.1.0 — 2021-08-10
- 1.0.1 — 2021-04-12
- 1.0.0 — 2020-09-11

## README

# Tracks

WooCommerce user event tracking utilities for Automattic based projects.

## Installation

Install the module

```bash
pnpm install @woocommerce/tracks --save
```

## Usage

The store must opt-in to allow tracking via the `woocommerce_allow_tracking` setting. 
If the store is not opted-in no events be recorded when using the following functions.

### recordEvent( eventName, eventProperties )

Record a user event to Tracks.

```jsx
import { recordEvent } from '@woocommerce/tracks';

recordEvent( 'page_view', { path } )
```

| Param | Type | Description |
| --- | --- | --- |
| eventName | `String` | The name of the event to record, don't include the `wcadmin_` prefix |
| eventProperties | `Object` | Event properties to include in the event |

### queueRecordEvent( eventName, eventProperties )

Queue a tracks event.

This allows you to delay tracks events that would otherwise cause a race condition.
For example, when we trigger `wcadmin_tasklist_appearance_continue_setup` we're simultaneously moving the user to a new page via
`window.location`. This is an example of a race condition that should be avoided by enqueueing the event,
and therefore running it on the next pageview.
| Param | Type | Description |
| --- | --- | --- |
| eventName | `String` | The name of the event to record, don't include the `wcadmin_` prefix |
| eventProperties | `Object` | Event properties to include in the event |

### recordPageView( path, extraProperties )

Record a page view to Tracks.

| Param | Type | Description |
| --- | --- | --- |
| path | `String` | Path the page/path to record a page view for |
| extraProperties | `Object` | Extra event properties to include in the event |

### bumpStat( statName, statValue )

Bump a stat or group of stats.

```typescript
import { bumpStat } from '@woocommerce/tracks';

// Bump a single stat
bumpStat( 'stat_name', 'stat_value' );

// Bump multiple stats
bumpStat( {
  stat1: 'value1',
  stat2: 'value2'
} );
```

| Param | Type | Description |
| --- | --- | --- |
| statName | `String` or `Object` | The name of the stat to bump, or an object of stat names and values |
| statValue | `String` | The value for the stat (only used when statName is a string) |

Note: Stat names are automatically prefixed with `x_woocommerce-`. Stat tracking is disabled in development mode.

## Debugging

When debugging is activated info for each recorded Tracks event is logged to the browser console.

To activate, open up your browser console and add this:

```js
localStorage.setItem( 'debug', 'wc-admin:*' );
```

---
_Source: https://npm.io/package/@woocommerce/tracks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._