npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

tracwell

v0.6.2

Published

Privacy-aware browser analytics, optional server-side AI crawler tracking, and the tracwell CLI for coding agents

Readme

SDK

Browser analytics SDK for page views, custom events, identity, batching, and delivery retries that outlast short Collector outages.

Script installation

The production browser artifact is served from the existing Collector domain:

<script
  defer
  src="https://collect.tracwell.app/script.js"
  data-project-key="tw_live_..."
  data-collection-mode="private"
></script>

Optional script attributes

| Attribute | Values | Default | | --- | --- | --- | | data-project-key | Your public project key (never a server key) | Required | | data-collection-mode | private, product | private | | data-consent | granted, required, denied | granted | | data-respect-do-not-track | true, false | true |

Keep collection mode explicit and aligned with website settings. The generated snippet omits default consent and Do Not Track attributes. Add data-consent="required" to wait for consent before identity creation or event collection. After the script loads, forward the visitor's saved choice and subsequent changes using window.tracwell?.setConsent("granted") or window.tracwell?.setConsent("denied"). An early call before the script loads has no effect; initialize the consent integration after SDK load.

Only these four data attributes are supported. Use the npm SDK for other initialization options, including batching, persistence overrides, and a custom collector URL. The script reads attributes at load time and does not fetch configuration from the dashboard; update the installed snippet when changing website settings.

When consent and Do Not Track permit collection, loading the script captures the initial page view and exposes the same client as window.tracwell for custom events:

window.tracwell?.track("signup_completed", { plan: "starter" });

The script derives /v1/events from its own origin, so the same artifact works against the loopback Collector during local development. The production bundle reports SDK version 0.2.0, targets ES2022-capable browsers, and has the accepted 5 KB (5,120-byte) gzip budget enforced by build:cdn.

Public API

Install the npm package:

pnpm add tracwell
import { createTracwell } from "tracwell";

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

tracwell.track("signup_completed", { plan: "starter" });
tracwell.identify("customer_123");

const session = tracwell.getSession();

createTracwell() starts collection immediately in the browser and captures the initial page view by default. It must be called after the document is available, not during server rendering.

Framework compatibility

The npm SDK is a framework-neutral ESM browser library. It has no React, Vue, Svelte, Angular, router, or rendering-framework dependency. Importing it during SSR is safe; call createTracwell() from that framework's browser mount or hydration lifecycle after document is available.

Multi-page applications capture a page view each time the browser loads the application. Single-page applications using the standard History API receive automatic page views for pushState, replaceState, and back/forward navigation. This covers the default path-based routers in modern web frameworks. Hash fragments remain intentionally excluded from analytics URLs; hash-only navigation does not create a page view.

Framework adapters should own only lifecycle integration and dependency injection. Event validation, identity, attribution, navigation observation, batching, retries, consent, and delivery remain in this core package.

Responsibilities

  • Generate stable event and batch IDs before delivery.
  • Capture initial page views, SPA navigation, referrer, UTM, and tagged-link context.
  • Expose typed custom-event and identity APIs.
  • Batch only against the limits exported by @tracwell/contracts.
  • Retry transient failures with backoff without changing event IDs.
  • Respect configured consent and Do Not Track behavior before collection.

The default SDK entry must remain browser-only, small, non-blocking, and unable to set trusted collector fields. It must not contain secrets or connect to ClickHouse. The separate server entry accepts a server-side key as documented below.

Identity and attribution

Collection mode is explicit:

  • private is the default. It never reads or writes cookies, localStorage, or sessionStorage; identify() reports IDENTIFY_UNAVAILABLE. Anonymous and session values exist only in memory until the collector replaces them.

  • product persists first-party anonymous, session, and optional user identity in localStorage. Configure consent before collection where required.

  • Private mode rejects an explicit persistence: "localStorage" instead of silently weakening the project's privacy behavior.

  • anonymous_id is first-party and persists per project unless persistence is disabled or identity is reset.

  • session_id rotates after 30 minutes without a captured event.

  • A different non-empty UTM campaign starts a new session immediately.

  • The first external referrer and UTM values are preserved for the session.

  • The SDK preserves the absolute referrer. Trusted ClickHouse row mapping uses registered-domain/public-suffix parsing so sibling subdomains are not reported as external acquisition.

  • identify() validates the supplied opaque user ID before associating it with future events.

  • Identifying a different user on the same installation rotates both anonymous identity and session before recording the new identity. Call reset() on logout so an anonymous post-logout visit also starts cleanly.

  • getSession() returns the active Product-mode anonymousId, sessionId, and optional userId so a server-created checkout can carry the same identifiers into an authenticated revenue event. It returns undefined in Private mode, without consent, when Do Not Track blocks collection, or after shutdown.

  • Treat the returned IDs as attribution context, not authorization. Revenue user_id must come from the authenticated account or verified payment webhook rather than a client-supplied value.

  • Hash-only URL changes do not create duplicate SPA page views.

  • URL fragments are excluded from captured URLs and path contains only the pathname.

Product identity uses localStorage, never fingerprinting. If storage is disabled or unavailable, the SDK explicitly reports STORAGE_UNAVAILABLE through onError and uses in-memory identity for the page lifetime.

Delivery semantics

  • Events receive lightweight client preflight validation before entering memory. The Collector remains the canonical Zod validation boundary for all untrusted browser input.
  • Normal cross-origin delivery uses a safelisted text/plain JSON body so it does not add a CORS preflight request; the collector still parses and validates the body as JSON.
  • Batches default to 25 events and are reduced when necessary to remain within the shared 48 KiB limit.
  • Normal delivery reports accepted only after a matching 202 receipt confirms the batch ID and event count.
  • Network errors, 408, 429, and 5xx responses are retried with backoff (2 s doubling, at most 5 minutes per wait) without changing event or batch IDs, until the oldest event nears the Collector's 24-hour age limit. An explicit maxRetries (0-5) caps attempts; by default there is no fixed cap. Periodic flushes wait for a scheduled retry; flush() and shutdown() send immediately.
  • While delivery is failing at most 100 events are held; the oldest waiting events are dropped and reported through onError.
  • Product mode with persistence: "localStorage" also stores held events under tracwell:<projectKey>:pending and resumes them on the next page load. Private mode never writes them to browser storage. Denying consent clears them. Resending an event a beacon already delivered is safe: event IDs are stable and deduplicated.
  • Other 4xx responses report DELIVERY_REJECTED and are not retried.
  • Page-hide and hidden-document delivery prefers sendBeacon; a successful browser handoff reports handed_off, never accepted.
  • Exhausted delivery is surfaced through onError with the affected event IDs.

The default collector endpoint is https://collect.tracwell.app/v1/events. Production overrides must use HTTPS; loopback HTTP is allowed only for local development.

Privacy controls

  • consent: "required" prevents identity creation and collection until setConsent("granted").
  • Revoking consent stops listeners, removes queued events, and resets identity.
  • Do Not Track is respected by default and can be disabled explicitly per customer configuration.
  • persistence: "none" keeps all identifiers in memory.
  • Private collection forces persistence: "none" and blocks identify().

Structure

src/
  index.ts         Stable public exports and browser-only factory
  script.ts        Lean self-starting CDN entry and `window.tracwell` exposure
  script-config.ts Strict script-dataset parsing and normalized CDN defaults
  client.ts        Consent-aware API and lifecycle orchestration
  config.ts        Defaults and configuration validation
  identity.ts      Anonymous, session, and user identity state
  attribution.ts   First-touch-per-session UTM and referrer capture
  events.ts        Context creation and contract-validated events
  transport.ts     Size-aware batching, receipts, beacon, and retries
  preflight.ts     Small client-side event and receipt checks
  runtime.ts       Browser API adapter
  types.ts         Public configuration, client, delivery, and error types
  client.test.ts   Deterministic SDK behavior and failure tests
  index.test.ts    SSR import and browser-initialization boundary
  cli/             The `tracwell` command (Node only, own tsconfig.cli.json)
    main.ts        Commands, help and output
    args.ts        Flag parsing
    config.ts      Saved login and default website (0600 file)
    oauth.ts       Browser login, refresh and revoke
    mcp.ts         JSON-RPC client for `/mcp`
    tool-arguments.ts  Flags to tool arguments, --site/--days/requestId
    install.ts     Skill and AGENTS.md install into the current repo
    definitions.ts `goals add` / `funnels add` step parsing
skills/tracwell/
  SKILL.md         Agent skill, shipped in the package and served at /skill.md
scripts/
  build-cdn.mjs    Minified browser build and gzip-size enforcement
  build-npm.mjs    Self-contained ESM package build, including dist/npm/cli.js
  smoke-npm.mjs    Packed runtime, TypeScript, CLI and skill consumer smoke test
static/
  _headers         Cross-origin browser asset headers

Keep browser globals isolated in runtime.ts, keep index.ts as the stable public API, and test behavior through an injected deterministic runtime.

Dependencies

  • @tracwell/contracts for inferred types and shared limits
  • Browser platform APIs for navigation, lifecycle, and delivery
  • esbuild at build time for the minified browser artifact

The published npm artifact bundles its runtime contract constants and ships generated declarations, so consumers do not need the private contracts workspace. Compile-time compatibility checks keep the duplicated public property and issue types aligned with the canonical contracts package.

The npm package is distributed under the MIT License. Publishing the package does not make the private application repository public.

Verify

pnpm --filter {packages/sdk} typecheck
pnpm --filter {packages/sdk} test
pnpm --filter {packages/sdk} build:cdn
pnpm --filter {packages/sdk} check:package

Server-only AI crawler entry

tracwell/server exports trackAiCrawler(request, { serverKey, statusCode?, collectorUrl? }). Import only on your backend; never expose tw_sk_ keys in browser code. This separate bundle adds nothing to the default browser entry or CDN script. Available starting with npm package version 0.3.0. The unchanged browser transport continues reporting browser SDK version 0.2.0.

Call from Next.js proxy/middleware or another server/edge handler. Pass the promise to the hosting runtime's waitUntil (and inspect its result), or await on a persistent server. Keep existing request handling intact. The helper ignores ordinary traffic, API paths and common static assets. Robots, sitemap and Markdown requests remain trackable. Handler/cache placement determines coverage.

Results are ignored, accepted (matching Queue receipt), or failed with a non-sensitive error code. Three total attempts use the same event ID, timestamp and sanitized URL. Retries are in memory only. Do not treat acceptance as confirmed database persistence. Queries/fragments are stripped; no IP, cookies or other request headers are sent. Raw UA is sent solely for collector classification and is not stored. Current provider matches are user-agent based, not IP verified. See the public /docs/ai-crawlers guide for setup and direct POST integration.

Use 0.3.1 or newer on Cloudflare Workers: crawler delivery uses manual redirect handling because Workers does not support the fetch redirect error mode. Redirect responses are rejected without forwarding the server key.

Version 0.4.0 expands server crawler recognition to 23 tokens across 12 providers. Existing server integrations must upgrade and redeploy to send newly supported crawlers; keys and browser installation are unchanged. The collector determines the purpose, including other for mixed/general crawling.

CLI

The package also installs a tracwell command for terminals and coding agents:

npx tracwell init --url https://acme.com   # sign in, find or add the site, snippet, skill
npx tracwell login            # browser sign-in; pick websites on the consent screen
npx tracwell sites add Acme https://acme.com
npx tracwell use <website-id>
npx tracwell snippet          # install snippet for the website
npx tracwell verify           # waiting / receiving
npx tracwell overview --days 30
npx tracwell goals add "Signed up" --event signup_completed --category signup
npx tracwell funnels add Checkout --steps /pricing,event:checkout_started
npx tracwell search funnel    # find tools by keyword
npx tracwell call funnel_create --name Checkout --dry-run
npx tracwell help overview    # arguments, read live from Tracwell
npx tracwell skill install    # .agents/skills/tracwell (and .claude/skills if present)
npx tracwell agents-md install

init signs in if there is no saved login, then picks the website: --site, else the one whose origin matches --url (it reads each website's install record, since the list has no URLs), else creates it with website_create (OAuth with "Add websites" only), else the saved or only website. It saves the website as the default, prints the snippet, and runs skill install and agents-md install. skill install leaves a copy that differs alone unless --force; agents-md install replaces only the marked tracwell:start/end block. --dry-run prints the tool, its arguments and whether it writes, without calling it; it still reads the tool list, so it needs a login.

It is a thin client for the existing /mcp endpoint: each command is one stateless tools/call, so the CLI has the same tools, permissions and plan checks as MCP and needs no API of its own. Short commands cover the common tools; tracwell call <tool> --arg value runs any other, and tracwell tools lists what the current login can use. Output is JSON (--compact for one line). Exit codes: 0 ok, 1 request failed, 2 bad input, 3 sign-in needed.

login registers a public OAuth client for a http://127.0.0.1:<port>/callback redirect, opens the consent page with S256 PKCE and the /mcp resource, and stores the access and refresh tokens. login --key, --key on any command, or TRACWELL_API_KEY use an API key instead; keys cannot add websites. Credentials live in $TRACWELL_CONFIG_DIR, else $XDG_CONFIG_HOME/tracwell or ~/.config/tracwell (%APPDATA%\tracwell on Windows), mode 0600. TRACWELL_URL points the CLI at another Tracwell origin. login goes to TRACWELL_URL or https://tracwell.app, never the saved login's address, so an old local login cannot trap it; other commands use the address of the saved login. logout revokes the OAuth grant and deletes the file.

The CLI is built as a separate Node 20 entry (dist/npm/cli.js); the browser and tracwell/server entries never import it. skills/tracwell/SKILL.md is the agent skill: sign in, add the site, install the snippet, verify, read reports. The web build serves the same file at https://tracwell.app/skill.md.