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

Built-in Code Destination:

For custom logic without external packages, use code: true:

See Destinations documentation for all available options.

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: { ... }                                           │
│  ├── 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​

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​