@dreamdata_io/analytics.js

Dreamdata's browser analytics script — a minimal, extensible client library that captures B2B events and delivers them to Dreamdata's tracking API.

This repo is the successor to our analytics-next fork. It started from Segment Analytics Next, stripped down to Dreamdata-only delivery while keeping the public API and wire contract compatible where it matters.

What ships

| Artifact | Description | | -------- | ----------- | | npm @dreamdata_io/analytics.js | ESM + CJS + TypeScript declarations for bundler-based apps. Safe to import from a server render (Next.js, Remix, Astro SSR); tracking itself still requires a browser | | dreamdata.min.js | Full-featured UMD bundle for CDN / <script> tag installs | | consent-loader.min.js | Self-gating consent loader (cookieless or full mode, never both) | | iframe-identify-form.min.js | Minimal iframe bundle for form identification | | window.dreamdata | Global queue + API surface used by the installation snippet |

Build outputs land in dist/esm, dist/cjs, dist/types, and dist/umd.

Canary CDN

Every push to main deploys the UMD bundles to a canary path, separate from analytics-next's production URL (.../scripts/analytics/next/), so the new script can be tested with opted-in customers first. Same bucket, reachable via any of Dreamdata's three CDN hostnames:

• https://cdn.dreamdata.cloud/scripts/analytics/canary/dreamdata.min.js
• https://cdn.dreamdata.cloud/scripts/analytics/canary/consent-loader.min.js
• https://cdn.dreamdata.cloud/scripts/analytics/canary/iframe-identify-form.min.js

(cdn.dreamdata.io and cdn.drda.io serve the same paths.) See .github/workflows/canary-deploy.yml.

Quick start (contributors)

Requires Bun 1.3+ and Node 20+.

bun install
bun run build
bun run check      # typecheck + lint + unit tests
bun run e2e        # Playwright (run after build)

Individual commands: bun run typecheck, bun run lint, bun run test, bun run test:watch.

Local demo

Manual playground for the built UMD bundle — open in a browser and click through API calls without hitting production.

bun run build   # once, or after source changes
bun run demo    # serves http://localhost:5438

Then open http://localhost:5438/demo/. Events are sent to a mocked /demo/api/v1/* endpoint on the same server. Additional demo pages live under /demo/ (consent, forms, CMP, manual tracking).

Set DEMO_PORT to override the default (5438). E2e uses port 3000 separately for Playwright — the two do not overlap.

Documentation

End-user and maintainer docs live in docs/ (Astro Starlight). Run locally with:

cd docs && bun install && bun run dev

Key pages:

• Installation — snippet and npm setup
• Architecture — event pipeline overview
• Project structure — codebase layout
• Build & release — CI and publishing

Repository layout

src/
  core/       Analytics engine (queue, delivery, storage, user identity)
  plugins/    Enrichment and integrations (env, forms, intent sources, consent)
  browser/    AnalyticsBrowser entry points and UMD standalone bundles
  loader/     Consent loader bundle
  lib/        Shared utilities
docs/         Starlight documentation site
demo/         Local browser playground (bun run demo)
e2e/          Playwright end-to-end tests

Start reading at src/core/analytics/core-analytics.ts, then follow events through src/core/queue/ and src/core/delivery/.

Wire compatibility

e2e/compat.spec.ts drives the same call sequence through both this repo's UMD bundle and a sibling ../analytics-next checkout, then diffs /api/v1 payloads field-for-field (normalizing only volatile fields like messageId and timestamps).

This is intentional regression protection — not a runtime dependency. The test skips when the reference bundle is absent.

Intentional legacy compatibility

Some Segment-era identifiers are kept on purpose for existing installs migrating to Dreamdata:

• Storage keys — ajs_* cookie and localStorage keys are read alongside dd_* keys (src/core/user/constants.ts)
• CDN paths — analytics.js/v1/{writeKey}/analytics.min.js URL patterns still resolve
• Query-string params — ajs_*-prefixed URL parameters are still parsed

Do not remove these without a migration plan and updated compat tests.