> For the complete documentation index, see [llms.txt](https://docs.reo.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reo.dev/set-up-npm-package-installs-tracking-on-reo.dev.md).

# Set-up NPM Package Installs Tracking on Reo.Dev

When developers install your package, it signals **real product usage.** With Reo.Dev, you can now identify and monitor installs of your NPM packages. This short guide will walk you through how this works and how you can set it up.

{% hint style="info" %}
**Note:** NPM install tracking works for developers installing packages via the terminal as well. No additional setup is required.
{% endhint %}

#### How NPM Install Tracking Works

Once `reo-census` is added to your package:

1. A developer installs your package using `npm install`.
2. The `reo-census` script runs automatically during installation.
3. Installation metadata is sent to **Reo’s telemetry endpoint**.
4. Reo processes the data and surfaces it as **developer activity signals** in your dashboard.

#### **Pre-requisites**

Before setting up NPM install tracking, please ensure the following are in place:

**1. Share your NPM package URL with Reo**

Provide your NPM package link (e.g. `https://www.npmjs.com/package/your-package`) to the Reo team so we can configure tracking on our end.

**2. Configure Product Usage Metrics in Reo**

You’ll need to create a metric to track installs:

* Go to Configurations > **Product Usage**
* Click on Create New
* Create a metric named: `npm_install`

<figure><img src="/files/qyXWgfYBfFTLm9oKJB1M" alt=""><figcaption></figcaption></figure>

This ensures all install events are correctly captured and surfaced as signals in your dashboard.

#### Configuring NPM Installs

Simply add `reo-census` to your `package.json`. Once done, you can track all de-anonymized developers who have installed your NPM package on Reo.

You’ll get:

* The Package name and version installed
* OS platform, architecture, Node.js version
* Install timestamp
* Git username and email domain (partial mode) or full email (full mode)

```json
{
  "name": "your-package",
  "version": "1.0.0",
  "dependencies": {
    "reo-census": "^1.2.8"
  }
}
```

{% hint style="info" %}
Note: By default, **NPM install tracking works automatically** once `reo-census` is added to your package. No additional setup is required.
{% endhint %}

However, if you want more control over how telemetry works, you can optionally configure tracking behavior by adding a **`reoSettings` block** inside your `package.json`. Here’s how you can set this up:

#### Additional Configurations (Optional)

**When Should You Use Optional Configuration?**

Most teams **do not need to configure anything**. However, you may want to customize settings if you need to:

* Disable tracking by default
* Send telemetry to a custom endpoint
* Capture additional metadata using full data mode

To add custom configurations, add the `reoSettings` block to your `package.json`.

```json
{
  "name":"your-package",
  "version":"1.0.0",
  "reoSettings": {
    "defaultOptIn":true,
    "endpoint":"<https://telemetry.reo.dev/data>",
    "dataMode":"partial"
  },
  "dependencies": {
    "reo-census":"^1.2.8"
  }
}
```

Here are details on the configuration options for `reoSettings`

**`defaultOptIn`**

This controls whether tracking is **enabled automatically** when someone installs your package.

**Default:** `true`

| Value   | Behavior                                                |
| ------- | ------------------------------------------------------- |
| `true`  | Tracking is enabled automatically                       |
| `false` | Tracking is disabled unless the user explicitly opts in |

Most packages keep this enabled so installs are automatically tracked.

**`endpoint`**

This defines the **destination where installation telemetry is sent**.

**Default endpoint:**

```
<https://telemetry.reo.dev/data>
```

This is the Reo telemetry service that processes install signals.

You only need to change this if you want to:

* Route telemetry through your own infrastructure
* Use a custom telemetry pipeline
* Debug install tracking

**`dataMode`**

This controls **how much information is sent during package installation**.

**Default:** `"partial"`

| Mode      | Description                                       |
| --------- | ------------------------------------------------- |
| `partial` | Sends only the email domain (e.g., `company.com`) |
| `full`    | Sends the full email address and dependency list  |

Note: If you don’t add a `reoSettings` block, Reo will automatically apply the following **default settings:**

* **`defaultOptIn: true`** → install tracking is enabled automatically
* **`endpoint: <https://telemetry.reo.dev/data`**> → telemetry is sent to Reo’s telemetry service
* **`dataMode: "partial"`** → only the developer’s email domain is captured (not the full email)

This means **NPM install tracking will work automatically** once `reo-census` is added to your package — no additional configuration required.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.reo.dev/set-up-npm-package-installs-tracking-on-reo.dev.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.