understanding-destinations

Use when working with destinations, understanding the destination interface, or learning about env pattern and configuration. Covers interface, lifecycle, env mocking, and paths.

⭐309stars🔀16forks📁View on GitHub🕐Updated Dec 19, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive technical guide to walkerOS Destinations, detailing the core interface, lifecycle management, and the 'env' pattern for dependency injection. It enables developers to effectively transform and deliver processed event data to third-party analytics, marketing tools, and data warehouses while maintaining clean, testable code through standardized configuration and testing patterns.

Use Cases

  • 1. Custom Destination Development: Implementing the required push and optional init methods to integrate new third-party APIs or data platforms into the walkerOS ecosystem.
  • 2. Unit Testing & Mocking: Leveraging the 'env' pattern to simulate external API responses and window objects, allowing for rigorous testing of data delivery logic without side effects.
  • 3. Advanced Data Mapping & Consent: Configuring destination-specific settings, event transformation rules, and consent states to ensure data compliance and accuracy before delivery.
  • 4. Transformer Chain Integration: Wiring destinations to specific transformer chains (e.g., data redaction) to process events after collection but before they reach the final destination.
nameunderstanding-destinations

Understanding walkerOS Destinations

Overview

Destinations receive processed events from the collector and deliver them to third-party tools (analytics, marketing, data warehouses).

Core principle: Destinations transform and deliver. They don't capture or process—that's sources and collector.

Destination Interface

See packages/core/src/types/destination.ts for canonical interface.

Method Purpose Required
init(context) Load scripts, authenticate Optional
push(event, context) Transform and send event Required
pushBatch(batch, context) Batch processing Optional
config Settings, mapping, consent Required

The env Pattern

Destinations use dependency injection via env for external APIs. This enables testing without mocking.

// Destination defines its env type
export interface Env extends DestinationWeb.Env {
  window: {
    gtag: Gtag.Gtag;
    dataLayer: unknown[];
  };
}

// Destination uses env, not globals
async function push(event, context) {
  const { env } = context;
  env.window.gtag('event', mappedName, mappedData);
}

Testing with env

REQUIRED SKILL: See testing-strategy for full testing patterns.

import { mockEnv } from '@walkeros/core';
import { examples } from '../dev';

const calls: Array<{ path: string[]; args: unknown[] }> = [];
const testEnv = mockEnv(examples.env.push, (path, args) => {
  calls.push({ path, args });
});

await destination.push(event, { ...context, env: testEnv });

expect(calls).toContainEqual({
  path: ['window', 'gtag'],
  args: ['event', 'purchase', expect.any(Object)],
});

Destination Config

config: {
  settings: { /* destination-specific */ },
  mapping: { /* event transformation rules */ },
  data: { /* global data mapping */ },
  consent: { /* required consent states */ },
  policy: { /* processing rules */ },
  queue: boolean,  // queue events
  dryRun: boolean, // test mode
}

Destination Paths

Type Path Examples
Web packages/web/destinations/ gtag, meta, api, piwikpro, plausible
Server packages/server/destinations/ aws, gcp, meta

Template Destination

Use as starting point: packages/web/destinations/plausible/

Transformer Wiring

Destinations can wire to post-collector transformer chains via the before property:

destinations: {
  gtag: {
    code: destinationGtag,
    before: 'redact'  // First transformer to run before this destination
  }
}

The transformer chain runs after collector enrichment, before the destination receives events. Each destination can have its own chain. See understanding-transformers for chain details.

Skills:

Source Files:

Package READMEs:

Documentation: