Custom Events & Logging

Lightweight isomorphic client for tracking custom events and structured logs in both browser and Node.js environments.

Installation

The @dwellcount/events package works in both browser and Node.js environments.

npm install @dwellcount/events

Basic Usage

import { EventClient } from '@dwellcount/events';

const client = new EventClient({
  siteId: 'YOUR_SITE_ID',
  endpoint: 'https://your-dashboard.com/api/ingest',
  batchSize: 10,        // Send when 10 events queued
  flushInterval: 5000,  // Or every 5 seconds
});

// Set version info
client.setFrontendVersion({ version: '1.2.0', commit: 'def456' });
client.setBackendVersion({ version: '2.1.0', commit: 'abc123' });

// Track custom events
client.track('user_signup', { plan: 'pro', source: 'landing' });
client.track('button_clicked', { buttonId: 'cta-hero' });

// Identify users
client.identify('user_123', { email: 'user@example.com', plan: 'pro' });

// Flush before exit (important for Node.js)
await client.flush();

Structured Logging

All logs are tied to the current session and version info for full correlation.

// Log with levels
client.debug('Cache miss', { key: 'user:123' });
client.info('User completed onboarding', { userId: '123' });
client.warn('Rate limit approaching', { current: 95, limit: 100 });
client.error('Payment processing failed', { error: 'Card declined' });

// Log with explicit level
client.log('info', 'Custom message', { custom: 'metadata' });

// Track errors with stack traces
try {
  await riskyOperation();
} catch (error) {
  client.trackError(error, { context: 'checkout' });
}

When to Use @dwellcount/events

Use Framework Packages

For React, Vue, Svelte, or Angular apps, use the dedicated framework packages. They wrap this package with framework-specific APIs.

Use @dwellcount/events

For vanilla JS, custom setups, or when you need direct control over the event client in any environment.

API Reference

Method	Description
track(event, props?)	Track a custom event
identify(userId, traits?)	Identify a user
log(level, message, meta?)	Log a structured message
debug/info/warn/error(msg, meta?)	Log with specific level
trackError(error, context?)	Track an error with stack trace
setFrontendVersion(version)	Set frontend version info
setBackendVersion(version)	Set backend version info
flush()	Flush pending events immediately