reova

Lightweight, opt-in install telemetry for npm packages. After someone installs your package, reova can report a small set of signals — enough to see where adoption is happening and which organizations are pulling your library — to an analytics endpoint you choose.

Nothing is sent unless a consuming package turns it on and sets that endpoint. Never blocks an install.

Setup

Add reova as a dependency and configure it in your package.json:

{
  "name": "your-package",
  "version": "1.0.0",
  "reova": {
    "enabled": true,
    "endpoint": "https://analytics.your-domain.com/data"
  },
  "dependencies": {
    "reova": "^0.7.0"
  }
}

Both enabled: true and a valid endpoint are required — reova sends nothing until both are set. There is no default endpoint.

Configuration

| Key | Location | Required | Description | |-----|----------|:--------:|-------------| | enabled | package.json → reova.enabled | yes | true to opt in. Anything else = disabled. | | endpoint | package.json → reova.endpoint | yes | Where events are POSTed. http/https only. No default. |

Flags (environment variables)

| Variable | Effect | |----------|--------| | REOVA_ENDPOINT | Override the endpoint. | | REOVA_ENABLED=true | Force-enable (still requires an endpoint). | | REOVA_ANALYTICS=false | Global kill-switch — disables everything. | | DO_NOT_TRACK=1 | Also disables everything. | | REOVA_VERBOSE=true | Log what is sent to the console. |

Programmatic usage

Besides the automatic install-time event, you can import reova and send the same event yourself, at a time of your choosing.

track() is non-blocking by default — the POST is fired in the background, so it never blocks your callers even if the endpoint is slow or unreachable, and it never keeps a short-lived process alive. It returns true (queued) / false (opted out or no endpoint) almost immediately.

CommonJS:

const reova = require('reova');

// Fire-and-forget (default) — never blocks, safe on request/hot paths:
reova.track({
  endpoint: 'https://analytics.your-domain.com/data', // or reova.endpoint / REOVA_ENDPOINT
  packageName: 'your-package',        // optional overrides
  packageVersion: '1.0.0',
  activityType: 'feature_used',       // optional, defaults to 'npm_install'
  properties: { feature: 'checkout' } // optional extra fields
});

ESM:

import reova from 'reova';

reova.track({
  endpoint: 'https://analytics.your-domain.com/data',
  activityType: 'feature_used',
  properties: { feature: 'checkout' }
});

Want to wait for the network result (e.g. a CLI/cron that must confirm delivery before exiting)? Pass blocking: true:

const result = await reova.track({ blocking: true, endpoint: '…' });
// result → { success: true, statusCode: 200 }  (or { success: false, ... })

Send only once (ever)

Use once: true to send an event at most once per machine, even across restarts — e.g. a first-launch / activation signal:

reova.track({
  once: true,
  onceKey: 'first-launch',   // distinct key per once-event (default: package name)
  endpoint: 'https://analytics.your-domain.com/data'
});

• A small marker is stored under ~/.reova (override with REOVA_STATE_DIR), keyed by onceKey.
• The marker is written only on confirmed delivery, so a failed send retries on a later call rather than being lost.
• If it has already been delivered, track() returns false and sends nothing.
• Use a distinct onceKey for each independent once-event. To reset, delete the marker file(s) under ~/.reova.

Survives version upgrades and reinstalls. Because the marker lives in ~/.reova (outside node_modules) and the default onceKey is version-independent, upgrading your package — or deleting node_modules and reinstalling — does not re-fire the event. "Once ever" means once ever on that machine.

Want it once per version instead? Put the version in the key, so each new release is a fresh once-event:

const { version } = require('./package.json');

reova.track({
  once: true,
  onceKey: `first-launch@${version}`, // fires once per version (re-fires on upgrade)
  endpoint: 'https://analytics.your-domain.com/data'
});

⚠️ With once + non-blocking in a short-lived process, use blocking: true so the marker is written before the process exits (otherwise the detached send may be abandoned and the marker not recorded, causing a resend next run).

• Importing has no side effects — it does not run the postinstall or exit the process.
• Calling track() is the opt-in, so it does not require reova.enabled. It still honors the global kill-switches (REOVA_ANALYTICS=false / DO_NOT_TRACK) and still requires an endpoint (option, reova.endpoint, or REOVA_ENDPOINT).
• Same payload as the automatic flow; best-effort and never throws.

The automatic postinstall flow is unchanged.

Opt out

REOVA_ANALYTICS=false npm install
# or
DO_NOT_TRACK=1 npm install

On install, reova sends the package name/version, OS/arch/Node version, a CI flag, a random per-event id, and your git email domain (domain only, e.g. company.com — never the full address) to the configured endpoint. It is best-effort and never blocks or delays an install.

License

MIT