understanding-destinations
适用于处理目标、理解目标接口或学习环境模式和配置时使用。涵盖接口、生命周期、环境模拟和路径。
name: understanding-destinations description: Use when working with destinations, understanding the destination interface, or learning about env pattern and configuration. Covers interface, lifecycle, env mocking, and paths.
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.
Related
Skills:
- understanding-mapping skill - Configure transformations
- understanding-transformers skill - Transformer chaining to destinations
- testing-strategy skill - Test with env pattern
- create-destination skill - Create new destination
Source Files:
- packages/core/src/types/destination.ts - Interface
Package READMEs:
- packages/web/destinations/gtag/README.md - gtag example
- packages/web/destinations/plausible/README.md - Plausible (template)
Documentation:
- Website: Destinations - Overview
- Website: Create Your Own - Guide