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 (currently1)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 importpath- Local filesystem path (takes precedence overversion)
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 statespolicy- 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 eventconsent- 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:
Variables and definitions
Variables
Variables allow dynamic values with environment variable support:
Variable syntax:
${VAR_NAME}- Required variable${VAR_NAME:default}- Variable with default value
Resolution order:
process.env(environment variables)- Config-level
variables - Setup-level
variables - Inline default value
Definitions
Definitions allow reusable configuration blocks:
Type hierarchy
walkerOS uses a clear type hierarchy:
┌─────────────────────────────────────────────────────────────────┐
│ Flow.Setup (config file) │
│ ├── version: 1 │
│ ├── variables?: { GA_ID: "G-XXX" } │
│ ├── definitions?: { commonMapping: {...} } │
│ └── flows: │
│ └── default: Flow.Config │
└─────────────────────────────────────────────────────────────────┘
│
│ CLI resolves variables, $refs
▼
┌─────────────────────────────────────────────────────────────────┐
│ 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 CLIFlow.Config- Single flow configurationCollector.InitConfig- Runtime type passed tostartFlow()
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