Flow Configuration
Flow configuration is walkerOS's "configuration as code" approach. A single JSON file defines your entire event collection pipeline—sources, collector, destinations, and packages—making it portable, version-controlled, and deployable across environments.
Philosophy
If you're familiar with Segment, Jitsu, or Amplitude—think of flow configuration as your sources, destinations, and transformation rules defined in one file instead of a web UI. This approach provides:
- Version control: Track changes in git like any other code
- Reproducibility: Same config = same behavior across environments
- Portability: Move between local, staging, and production seamlessly
- Transparency: No hidden settings in external dashboards
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 creates an HTTP event collection endpoint that logs events to the console.
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
Common Sources:
@walkeros/server-source-express- HTTP event collection endpoint@walkeros/web-source-browser- Browser DOM event tracking@walkeros/web-source-dataLayer- DataLayer integration
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
Common Destinations:
@walkeros/destination-demo- Console logging (great for testing)@walkeros/server-destination-gcp- Google BigQuery@walkeros/server-destination-aws- AWS services@walkeros/web-destination-gtag- Google Analytics 4@walkeros/web-destination-meta-pixel- Meta Pixel
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