Bundled mode

In Bundled mode, you configure walkerOS with JSON files and build standalone bundles using the CLI. The output is a separate file that can be deployed independently of your application.

Quickstart

1. Install the CLI

npm install -g @walkeros/cli

# Verify installation
walkeros --version

2. Create a flow configuration

Create flow.json:

Web (browser)

{
"version": 4,
"flows": {
  "default": {
    "config": {
      "platform": "web",
      "bundle": {
        "packages": {
          "@walkeros/collector": {},
          "@walkeros/web-source-browser": {}
        }
      }
    },
    "sources": {
      "browser": {
        "package": "@walkeros/web-source-browser",
        "config": {
          "settings": {
            "pageview": true,
            "session": true
          }
        }
      }
    },
    "collector": { "run": true }
  }
}
}

Server (Node.js)

{
"version": 4,
"flows": {
  "default": {
    "config": {
      "platform": "server",
      "bundle": {
        "packages": {
          "@walkeros/collector": {},
          "@walkeros/server-source-express": {},
          "@walkeros/destination-demo": {}
        }
      }
    },
    "sources": {
      "http": {
        "package": "@walkeros/server-source-express",
        "config": {
          "settings": { "path": "/collect", "port": 8080 }
        }
      }
    },
    "destinations": {
      "console": {
        "package": "@walkeros/destination-demo",
        "config": {
          "settings": { "name": "Event Logger" }
        }
      }
    },
    "collector": { "run": true }
  }
}
}

3. Build the bundle

walkeros bundle flow.json

This writes the bundle to stdout. Use -o to write to a file:

• Web: -o ./dist/walker.js (IIFE format, loadable via script tag)
• Server: -o ./dist/bundle.mjs (ESM format, runnable with Node.js)

4. Deploy

Web

Add to your HTML:

<script src="/walker.js"></script>

Server

Run directly:

node ./dist/bundle.mjs

Or with Docker:

walkeros run flow.json

---

Adding destinations

Add destinations to your flow.json:

{
"version": 4,
"flows": {
  "default": {
    "config": {
      "platform": "web",
      "bundle": {
        "packages": {
          "@walkeros/collector": {},
          "@walkeros/web-source-browser": {},
          "@walkeros/web-destination-api": {},
          "@walkeros/web-destination-gtag": {}
        }
      }
    },
    "sources": {
      "browser": {
        "package": "@walkeros/web-source-browser",
        "config": { "settings": { "pageview": true } }
      }
    },
    "destinations": {
      "api": {
        "package": "@walkeros/web-destination-api",
        "config": {
          "settings": { "url": "https://your-api.com/events" }
        }
      },
      "ga4": {
        "package": "@walkeros/web-destination-gtag",
        "config": {
          "settings": {
            "ga4": { "measurementId": "G-XXXXXXXXXX" }
          }
        }
      }
    },
    "collector": { "run": true }
  }
}
}

Rebuild: walkeros bundle flow.json

---

Adding consent

Add consent requirements in the destination config:

"destinations": {
"api": {
  "package": "@walkeros/web-destination-api",
  "config": {
    "settings": { "url": "https://your-api.com/events" },
    "consent": { "functional": true }
  }
},
"ga4": {
  "package": "@walkeros/web-destination-gtag",
  "config": {
    "settings": { "ga4": { "measurementId": "G-XXXXXXXXXX" } },
    "consent": { "analytics": true }
  }
}
}

Set consent at runtime:

// After loading walker.js
elb('walker consent', { functional: true, analytics: true });

---

Key concepts

The package: property

In Bundled mode, you reference packages by name:

"sources": {
  "browser": {
    "package": "@walkeros/web-source-browser"
  }
}

The CLI downloads and bundles the package. This differs from Integrated mode where you use code: with a direct import.

Variables and environment

Use variables for environment-specific values:

{
"version": 4,
"variables": {
  "GA_ID": "$env.GA_MEASUREMENT_ID:G-DEFAULT",
  "API_URL": "$env.API_ENDPOINT:https://api.example.com"
},
"flows": {
  "default": {
    "destinations": {
      "ga4": {
        "config": {
          "settings": { "ga4": { "measurementId": "$var.GA_ID" } }
        }
      }
    }
  }
}
}

Environment variables ($env.NAME:default) are resolved at build time. Config variables ($var.name) reference values from the variables section.

Multiple flows

Define different flows for different environments:

{
"version": 4,
"flows": {
  "development": {
    "config": { "platform": "web" },
    "destinations": {
      "console": { "package": "@walkeros/destination-demo" }
    }
  },
  "production": {
    "config": { "platform": "web" },
    "destinations": {
      "ga4": { "package": "@walkeros/web-destination-gtag" }
    }
  }
}
}

Build specific flow: walkeros bundle flow.json --flow production

---

CLI commands

Command	Purpose
walkeros bundle	Build production bundle
walkeros push --simulate	Test with mocked events
walkeros push	Test with real API calls
walkeros run	Start HTTP collection server

See CLI documentation for full details.

---

Docker deployment

For production server deployments:

# Build the bundle
walkeros bundle flow.json

# Run with Docker
docker run -d -p 8080:8080 \
-v $(pwd)/dist/bundle.mjs:/app/flow.mjs \
-e BUNDLE=/app/flow.mjs \
walkeros/flow:latest

See Docker documentation for complete deployment guides.

---

See your event

Before you build and deploy, run the event through the flow offline with the named destination mocked.

Web (browser)

Using the flow.json with destinations you created above, push builds the flow and runs the event through it with the named destination mocked. Nothing is sent to a vendor.

npx walkeros push flow.json \
-e '{"name":"page view"}' \
--simulate destination.ga4

Server (Node.js)

Using the server flow.json above (which defines the console destination), push builds and simulates it:

npx walkeros push flow.json \
-e '{"name":"page view"}' \
--simulate destination.console

push --simulate builds the flow, runs the event through it with destination.console replaced by a mock, and prints the resolved outcome (success and Duration); add --json to get the same result as JSON. Nothing is sent to a vendor. Event names use a space (page view).

---

Next steps

• CLI documentation: All CLI commands and options
• Docker deployment: Production container deployment
• Mapping: Transform events for destinations

---

See also

• Integrated mode: Build into your app with TypeScript
• Collector reference: Understanding the collector engine