Flow

Flow configuration is walkerOS's "configuration as code" approach. A single JSON file defines your entire event collection pipeline, making it portable, version-controlled, and deployable across environments.

Configuration structure

A flow configuration uses the Flow.Setup format with two required fields:

version - Schema version (currently 1)
flows - Named flow configurations

Basic example

This captures browser DOM events and sends them to your analytics API endpoint via HTTP POST requests.

Config syntax: `package:` vs `code:`

When configuring sources and destinations, you'll see two different syntaxes depending on your operating mode.

Bundled mode (JSON with CLI)

Use package: with a string reference. The CLI downloads and bundles the npm package:

Integrated mode (TypeScript with startFlow)

Use code: with a direct import reference:

Quick reference

Property	Mode	Value	When to Use
`package:`	Bundled	`"@walkeros/..."` (string)	CLI resolves and bundles from npm
`code:`	Integrated	`sourceBrowser` (import)	Direct code reference in your app

Both achieve the same result. The difference is whether the CLI bundles the code for you (Bundled) or you import it directly (Integrated).

See Operating Modes for more details on choosing your approach.

Flow configuration (Flow.Config)

Each flow in flows is a Flow.Config that defines runtime behavior.

Platform

Platform is determined by the presence of the web or server key:

Platform options:

"server": {} - Node.js server environment (HTTP endpoints, cloud functions)
"web": {} - Browser environment (client-side tracking)

The CLI automatically applies platform-specific build defaults:

Web: IIFE format, ES2020 target, output to ./dist/walker.js
Server: ESM format, Node20 target, output to ./dist/bundle.mjs

Packages

Specifies npm packages to download and bundle:

Properties:

version - npm version (semver or "latest", defaults to "latest")
imports - Array of named exports to import
path - Local filesystem path (takes precedence over version)

For development or custom packages, use path to reference a local directory:

See Local Packages in the CLI documentation for more details.

Sources

Sources capture events from various inputs. Each source needs:

package - The npm package (with optional version)
config - Source-specific settings

See Sources documentation for all available options.

Destinations

Destinations receive processed events and send them to analytics tools, databases, or APIs:

Configuration options:

settings - Destination-specific configuration (API keys, endpoints, etc.)
mapping - Event transformation rules (see Mapping documentation)
consent - Required consent states
policy - Processing rules

Conditional activation:

Sources and destinations support require to delay initialization until specific collector events fire. Use require: ["consent"] to prevent loading until consent is granted:

See Destinations documentation for all available options.

Transformers

Transformers process events between sources and destinations. They validate, enrich, or redact events in the pipeline.

Configuration options:

package - The npm package (required)
code - Explicit import variable name (optional, auto-resolved)
config - Transformer-specific configuration
env - Environment-specific settings
next - Next transformer in chain (omit to end chain)
variables - Transformer-level variable overrides
definitions - Transformer-level definitions

Chaining transformers:

Link transformers together using next:

Explicit chain control with arrays:

For explicit control over the transformer chain order, use an array instead of a string. This bypasses the automatic chain resolution:

Syntax	Behavior
`"next": "validate"`	Walks chain via each transformer's `next` property
`"next": ["validate", "enrich"]`	Uses exact order specified, ignores transformer `next` properties

Connecting to sources and destinations:

Pre-collector chain: Use next on a source to route events through transformers before the collector
Post-collector chain: Use before on a destination to route events through transformers after the collector

Both next and before accept arrays for explicit chain control (see "Explicit chain control with arrays" above).

See Transformers documentation for available transformers and custom transformer guide.

Inline Code (without packages)

For simple one-liner logic, define sources, transformers, or destinations inline without creating a package.

Use code object instead of package:

Inline Transformer:

Inline Destination:

Code object properties:

push - The push function with $code: prefix (required)
type - Optional instance type identifier
init - Optional init function with $code: prefix

Rules:

Use package OR code, never both
config stays separate (same as package-based)
$code: prefix outputs raw JavaScript at bundle time

Collector

The collector processes events from sources and routes them to destinations:

Options:

run - Whether to start the collector automatically (default: true)
globals - Properties added to every event
consent - Default consent state

See Collector documentation for complete options.

Web-specific options

For browser bundles, you can configure window variable names:

Properties:

windowCollector - Global variable name for collector instance (default: "collector")
windowElb - Global variable name for event tracking function (default: "elb")

Multi-flow configuration

For managing dev/staging/production flows in one file:

Build specific flows using the CLI:

Dynamic patterns

Flow configurations support four dynamic patterns for reusable, environment-aware configs:

`$var.name` - Config Variables

Reference variables defined in variables for shared values across your config:

Variables can be defined at three levels (higher specificity wins):

Source/Destination level - Highest priority
Flow (Config) level - Middle priority
Setup level - Lowest priority

`$env.NAME` - Environment Variables

Reference environment variables with optional defaults:

Syntax:

$env.GA4_ID - Required, throws if not set
$env.GA4_ID:default - Uses "default" if not set

Why only $env supports defaults

Environment variables are external and unpredictable - they might not be set in all environments. Config variables ($var) are explicitly defined, so a missing one indicates a configuration error.

`$def.name` - Definition References

Reference reusable configuration blocks defined in definitions:

Definitions cascade like variables - defined at setup, flow, or source/destination level.

`$code:` - Inline JavaScript

Embed JavaScript code directly in JSON config values:

The $code: prefix is stripped during bundling, outputting raw JavaScript:

Use cases:

fn: callbacks - Transform values in mapping
condition: predicates - Conditional event processing
Custom logic - Any inline function or expression

Syntax notes:

Multi-line code: Use JSON escapes (\n, \")
Scope: Same as bundled code (access to imports and variables)
Errors: Caught at build time by TypeScript/esbuild

Type hierarchy

walkerOS uses a clear type hierarchy:

┌─────────────────────────────────────────────────────────────────┐
│  Flow.Setup (config file)                                       │
│  ├── version: 1                                                 │
│  ├── variables?: { currency: "EUR" }                            │
│  ├── definitions?: { commonMapping: {...} }                     │
│  └── flows:                                                     │
│       └── default: Flow.Config                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ CLI resolves $var, $env, $def
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Flow.Config (resolved flow)                                    │
│  ├── web: {} or server: {}                                      │
│  ├── packages: { ... }                                          │
│  ├── sources: { ... }                                           │
│  ├── transformers: { ... }                                      │
│  ├── destinations: { ... }                                      │
│  └── collector: { ... }                                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ CLI bundles and transforms
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Collector.InitConfig (runtime)                                 │
│  Passed to startFlow() at runtime                               │
└─────────────────────────────────────────────────────────────────┘

Flow.Setup - Root config file format for CLI
Flow.Config - Single flow configuration
Collector.InitConfig - Runtime type passed to startFlow()

Complete example

Here's a production-ready flow that accepts HTTP events and sends them to BigQuery:

Programmatic usage

You can also use configuration programmatically with the startFlow function:

See the Collector documentation for complete API reference.

Next steps

CLI - Learn how to bundle and test flows
Docker - Deploy flows in containers
Sources - Explore available event sources
Destinations - Configure analytics destinations
Mapping - Transform events for destinations

💡 Need Professional Support?

Need professional support with your walkerOS implementation? Check out our services.

Configuration structure​

Basic example​

Config syntax: package: vs code:​

Bundled mode (JSON with CLI)​

Integrated mode (TypeScript with startFlow)​

Quick reference​

Flow configuration (Flow.Config)​

Platform​

Packages​

Sources​

Destinations​

Transformers​

Inline Code (without packages)​

Collector​

Web-specific options​

Multi-flow configuration​

Dynamic patterns​

$var.name - Config Variables​

$env.NAME - Environment Variables​

$def.name - Definition References​

$code: - Inline JavaScript​

Type hierarchy​

Complete example​

Programmatic usage​

Next steps​