Skip to main content

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 build settings—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 has two main sections:

  1. flow - Runtime configuration (sources, destinations, collector)
  2. build - Build-time configuration (packages, output format, optimization)

Basic Example​

Loading...

This creates an HTTP event collection endpoint that logs events to the console.

Flow Section​

The flow section defines runtime behavior—what happens when your application runs.

Platform​

Specifies the execution environment:

Loading...

Options:

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

Sources​

Sources capture events from various inputs. Each source needs:

  • code - The imported function name (from build.packages.imports)
  • config - Source-specific settings
Loading...

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. Structure is similar to sources:

Loading...

Configuration Options:

  • settings - Destination-specific configuration (API keys, endpoints, etc.)
  • mapping - Event transformation rules (see Mapping documentation)
  • consent - Required consent states
  • policy - 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

See Destinations documentation for all available options.

Collector​

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

Loading...

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.

Build Section​

The build section defines build-time behavior—how your flow is bundled into executable code.

Packages​

Specifies npm packages to download and bundle:

Loading...

Properties:

  • version - npm version (semver or "latest")
  • imports - Array of named exports to import

Output Options​

Loading...

Properties:

  • output - Output file path (default: ./dist/bundle.js)
  • minify - Minify the output (default: true)
  • format - Output format: "esm", "cjs", or "iife" (default: "esm")

Web-Specific Options​

For browser bundles (platform: "web"):

Loading...

Properties:

  • windowCollector - Global variable name for collector instance
  • windowElb - Global variable name for event tracking function

Multi-Environment Configuration​

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

Loading...

Build specific environments using the CLI:

Loading...

Complete Example​

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

Loading...

Programmatic Usage​

You can also use flow configuration programmatically with the startFlow function:

Loading...

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.