@v-tilt/core

Framework-agnostic primitives shared by the vTilt SDKs.

Internal package. @v-tilt/core is private and not published to npm. It is bundled into @v-tilt/browser and @v-tilt/node at build time, so integrators never install it directly. It exists only to keep cross-SDK logic in one place.

What lives here

Only logic that is genuinely identical across SDKs and depends on nothing but the JavaScript runtime (so it runs in the browser, Node, Cloudflare Workers and Deno alike):

| Module | Exports | Why it is shared | | ------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | compression.ts | Compression, MIN_COMPRESSION_SIZE, jsonStringify, withCompressionParam, gzipToBytes | Both SDKs POST batches to the same ingestion endpoint, which decodes compression=gzip-js over the raw bytes. The gzip call, the compression= URL flag, and the bigint-safe JSON serializer must stay byte-identical. | | uuidv7.ts | uuidv7 | Time-ordered $insert_id generation used for idempotency/ordering. | | event-emitter.ts | EventEmitter, Listener | Minimal typed emitter for SDK lifecycle hooks, with no dependency on Node's events. |

What does NOT belong here

• Anything that touches the DOM, navigator, XMLHttpRequest, Blob, or browser transport selection — that stays in @v-tilt/browser (request.ts, session-recording.ts).
• Anything that depends on Node-specific globals.
• The browser's SimpleEventEmitter — it is intentionally separate: it is string-keyed with once/wildcard support and logger integration, and is wired into many browser-only features.

Consumption

Both SDKs add @v-tilt/core as a workspace:* dev dependency and bundle it (Rollup node-resolve). fflate stays external so a single copy is deduped by the consuming package. Build @v-tilt/core before the SDKs — Turborepo's ^build ordering handles this automatically.

# from repo root
pnpm --filter @v-tilt/core build
pnpm --filter @v-tilt/node build

Scripts

pnpm run build        # rollup → dist (CJS + ESM + d.ts)
pnpm run type-check   # tsc --noEmit
pnpm run lint         # eslint
pnpm run test         # jest