> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# walker.js

Walker.js is a pre-built walkerOS application that combines both the [browser](https://www.walkeros.io/docs/sources/web/browser.md) and [dataLayer](https://www.walkeros.io/docs/sources/web/dataLayer.md) sources with the [collector](https://www.walkeros.io/docs/collector.md) and a default `dataLayer` destination into a pre-build package. It's designed for users who want instant web tracking without complex setup or configuration.

## Installation[​](#installation "Direct link to Installation")

### Option 1: npm package[​](#option-1-npm-package "Direct link to Option 1: npm package")

```
npm install @walkeros/walker.js
```

### Option 2: CDN[​](#option-2-cdn "Direct link to Option 2: CDN")

```
<script
  async
  data-elbconfig="elbConfig"
  src="https://cdn.jsdelivr.net/npm/@walkeros/walker.js@latest/dist/walker.js"
></script>
```

## Basic setup[​](#basic-setup "Direct link to Basic setup")

### 1. Add event queueing (recommended)[​](#1-add-event-queueing-recommended "Direct link to 1. Add event queueing (recommended)")

Add this script before walker.js loads to queue events during initialization:

```
<script>
  function elb() {
    (window.elbLayer = window.elbLayer || []).push(arguments);
  }
</script>
```

### 2. Include walker.js[​](#2-include-walkerjs "Direct link to 2. Include walker.js")

```
<script async data-elbconfig="elbConfig" src="./walker.js"></script>
```

### 3. Configure destinations[​](#3-configure-destinations "Direct link to 3. Configure destinations")

```
<script>
  window.elbConfig = {
    collector: {
      destinations: {
        console: {
          push: (event) => console.log('Event:', event),
        },
        api: {
          push: async (event) => {
            await fetch('/api/events', {
              method: 'POST',
              body: JSON.stringify(event),
            });
          },
        },
      },
    },
  };
</script>
```

## Configuration options[​](#configuration-options "Direct link to Configuration options")

Walker.js supports multiple configuration approaches with different priorities:

1. **Script tag `data-elbconfig`** (highest priority)
2. **`window.elbConfig`** (default fallback)
3. **Manual initialization** (when `run: false`)

### Settings[​](#settings "Direct link to Settings")

| Property    | Type             | Description                                                             | More |
| ----------- | ---------------- | ----------------------------------------------------------------------- | ---- |
| `collector` | `any`            | Collector configuration (Collector.InitConfig)                          |      |
| `browser`   | `any`            | Browser source configuration (Partial\<SourceBrowser.Settings>)         |      |
| `dataLayer` | `boolean \| any` | DataLayer configuration (boolean \| Partial\<SourceDataLayer.Settings>) |      |
| `elb`       | `string`         | Name for the global elb function (default: "elb")                       |      |
| `name`      | `string`         | Name for the global instance                                            |      |
| `run`       | `boolean`        | Auto-run on initialization (default: true)                              |      |

#### Browser source settings[​](#browser-source-settings "Direct link to Browser source settings")

| Property   | Type                       | Description                                                                                                                                                              | More |
| ---------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| `prefix`   | `string`                   | Prefix for data attributes (default: data-elb)                                                                                                                           |      |
| `scope`    | `string`                   | DOM scope for event tracking (default: document)                                                                                                                         |      |
| `pageview` | `boolean`                  | Enable automatic pageview tracking                                                                                                                                       |      |
| `capture`  | `boolean`                  | Read click/submit triggers in the capture phase so tagged elements are resolved at click time before app handlers run (set false for the previous bubble-phase behavior) |      |
| `elb`      | `string \| boolean`        | Name for global elb function, or false to install none                                                                                                                   |      |
| `name`     | `string`                   | Custom name for source instance                                                                                                                                          |      |
| `elbLayer` | `boolean \| string \| any` | Enable elbLayer for async command queuing (boolean, string, or Elb.Layer)                                                                                                |      |

#### DataLayer settings[​](#datalayer-settings "Direct link to DataLayer settings")

| Property | Type       | Description                                                              | More |
| -------- | ---------- | ------------------------------------------------------------------------ | ---- |
| `name`   | `string`   | DataLayer variable name (default: dataLayer)                             |      |
| `prefix` | `string`   | Event prefix for filtering which events to process                       |      |
| `filter` | `function` | Custom filter function: (event: unknown) => boolean \| Promise\<boolean> |      |

#### Collector settings[​](#collector-settings "Direct link to Collector settings")

| Property        | Type                           | Description                                                                                                 | More |
| --------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | ---- |
| `run`           | `boolean`                      | Whether to run collector automatically on initialization                                                    |      |
| `globalsStatic` | `WalkerOS.Properties`          | Static global properties that persist across collector runs                                                 |      |
| `sessionStatic` | `Collector.SessionStatic`      | Static session data that persists across collector runs                                                     |      |
| `logger`        | `Logger.Config`                | Logger configuration (level, handler)                                                                       |      |
| `queueMax`      | `number`                       | Maximum events retained in collector.queue (late-registration replay). FIFO drop on overflow. Default 1000. |      |
| `name`          | `string`                       | Flow name; keys this flow's entry in event.source.release and the observer flowId.                          |      |
| `release`       | `string`                       | Config release id stamped into event.source.release for this flow.                                          |      |
| `consent`       | `WalkerOS.Consent`             | Initial consent state                                                                                       |      |
| `user`          | `any`                          | Initial user data                                                                                           |      |
| `globals`       | `WalkerOS.Properties`          | Initial global properties                                                                                   |      |
| `sources`       | `Source.InitSources`           | Source configurations                                                                                       |      |
| `destinations`  | `Destination.InitDestinations` | Destination configurations                                                                                  |      |
| `transformers`  | `Transformer.Configs`          | Transformer configurations                                                                                  |      |
| `stores`        | `Store.Configs`                | Store configurations                                                                                        |      |
| `custom`        | `WalkerOS.Properties`          | Initial custom implementation-specific properties                                                           |      |
| `hooks`         | `Collector.Hooks`              | Pipeline observation hooks                                                                                  |      |
| `observe`       | `Observe`                      | Observation session connect config                                                                          |      |
| `observers`     | `Collector.Observers`          | Caller-supplied advisory observer functions                                                                 |      |

### Full configuration object[​](#full-configuration-object "Direct link to Full configuration object")

```
window.elbConfig = {
  // Global settings
  elb: 'elb', // Global function name (default: 'elb')
  name: 'walkerjs', // Global instance name
  run: true, // Auto-initialize (default: true)

  // Browser source settings
  browser: {
    run: true, // Auto-start DOM tracking
    session: true, // Enable session tracking
    scope: document.body, // Tracking scope
    pageview: true, // Enable automatic page views
  },

  // DataLayer integration
  dataLayer: true, // Enable dataLayer
  // or detailed config:
  // dataLayer: {
  //   name: 'dataLayer', // DataLayer variable name
  //   prefix: 'dataLayer', // Event prefix
  // },

  // Collector configuration
  collector: {
    consent: { functional: true }, // Default consent state
    destinations: {
      // Your destinations here
      console: {
        push: (event) => console.log('Event:', event),
      },
    },
  },
};
```

### Inline configuration[​](#inline-configuration "Direct link to Inline configuration")

Configure directly in the script tag using simple key<!-- -->:value<!-- --> pairs:

```
<script
  async
  data-elbconfig="elb:track;run:true;instance:myWalker"
  src="./walker.js"
></script>
```

### Named configuration object[​](#named-configuration-object "Direct link to Named configuration object")

Use a custom configuration object name:

```
<script>
  window.trackingConfig = {
    elb: 'track',
    collector: {
      destinations: {
        // Your destinations
      },
    },
  };
</script>
<script async data-elbconfig="trackingConfig" src="./walker.js"></script>
```

## Usage[​](#usage "Direct link to Usage")

### Automatic DOM tracking[​](#automatic-dom-tracking "Direct link to Automatic DOM tracking")

Walker.js automatically tracks events based on HTML data attributes:

```
<!-- Product tracking -->
<div data-elb="product" data-elb-product="id:123;name:Blue T-Shirt;price:29.99">
  <button data-elbaction="click:add">Add to Cart</button>
</div>

<!-- Global properties -->
<div data-elbglobals="pagetype:product_detail"></div>

<!-- Context information -->
<div data-elbcontext="section:recommendations"></div>
```

For detailed information on data attributes, see the [Browser Source documentation](https://www.walkeros.io/docs/sources/web/browser/tagging/html-attributes.md).

### Manual event tracking[​](#manual-event-tracking "Direct link to Manual event tracking")

Use the global `elb` function for manual tracking:

```
// Simple event
elb('button click', {
label: 'interesting',
});
```

### DataLayer integration[​](#datalayer-integration "Direct link to DataLayer integration")

Walker.js can integrate with existing dataLayer implementations:

```
// Enable dataLayer integration
window.elbConfig = {
dataLayer: true, // Uses window.dataLayer by default
};

// Existing dataLayer events will be processed
dataLayer.push({
event: 'purchase',
ecommerce: {
transaction_id: '12345',
value: 25.42,
},
});
```

## Advanced features[​](#advanced-features "Direct link to Advanced features")

### Async loading and event queueing[​](#async-loading-and-event-queueing "Direct link to Async loading and event queueing")

Walker.js handles async loading gracefully with automatic event queueing:

```
<script>
  // 1. Define elb function to queue events
  function elb() {
    (window.elbLayer = window.elbLayer || []).push(arguments);
  }

  // 2. Track events immediately (even before walker.js loads)
  elb('product view', { id: '123', name: 'Blue T-Shirt' });
</script>

<!-- 3. Walker.js processes queued events when it loads -->
<script async data-elbconfig="elbConfig" src="./walker.js"></script>
```

### Build variants[​](#build-variants "Direct link to Build variants")

Walker.js provides multiple build formats for different environments:

* `walker.js` - Standard IIFE bundle for browsers
* `index.es5.js` - GTM-compatible ES2015 build
* `index.mjs` - ES modules for modern bundlers
* `index.js` - CommonJS for Node.js environments

### Programmatic usage[​](#programmatic-usage "Direct link to Programmatic usage")

Use walker.js programmatically in applications:

```
import { createWalkerjs } from '@walkeros/walker.js';

const { collector, elb } = await createWalkerjs({
collector: {
destinations: {
console: { push: console.log },
},
},
browser: {
session: true,
pageview: true,
},
});
```

## Destination configuration[​](#destination-configuration "Direct link to Destination configuration")

Configure multiple destinations for your events:

```
window.elbConfig = {
collector: {
destinations: {
// Console logging for development
console: {
  push: (event) => console.log('Walker.js Event:', event),
},

// Custom API endpoint
api: {
  push: async (event) => {
    await fetch('/api/events', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event),
    });
  },
},
},
},
};
```

For comprehensive destination options, see the [Destinations documentation](https://www.walkeros.io/docs/destinations.md).

## Growing beyond walker.js[​](#growing-beyond-walkerjs "Direct link to Growing beyond walker.js")

Walker.js is a **convenience bundle** that combines Browser Source, DataLayer Source, and Collector into a single file. It's perfect for getting started, but you may outgrow it.

### When to stay with walker.js[​](#when-to-stay-with-walkerjs "Direct link to When to stay with walker.js")

* ✅ Simple tracking needs (pageviews, clicks, forms)
* ✅ Static sites or traditional server-rendered pages
* ✅ Quick proof-of-concept or MVP
* ✅ Teams who prefer minimal setup

### When to upgrade[​](#when-to-upgrade "Direct link to When to upgrade")

Consider moving to full [Integrated](https://www.walkeros.io/docs/getting-started/modes/integrated.md) or [Bundled](https://www.walkeros.io/docs/getting-started/modes/bundled.md) mode when you need:

| Need                            | Solution                          |
| ------------------------------- | --------------------------------- |
| Server-side tracking            | Bundled mode with Docker          |
| Custom sources (HTTP, AWS, GCP) | Both modes support server sources |
| Multiple flows per page         | Full Collector configuration      |
| TypeScript integration          | Integrated mode                   |
| CI/CD versioned configs         | Bundled mode                      |
| Event mapping/transformation    | Both modes with mapping config    |

### Migration path[​](#migration-path "Direct link to Migration path")

Walker.js configuration maps directly to full modes:

* Integrated
* Bundled

```
// walker.js equivalent in Integrated mode

import { startFlow } from '@walkeros/collector';

import { sourceBrowser } from '@walkeros/web-source-browser';



const { elb } = await startFlow({

  sources: {

    browser: {

      code: sourceBrowser,

      config: { settings: { pageview: true, session: true } },

    },

  },

  destinations: {

    // Your destinations here

  },

  run: true,

});
```

```
// walker.js equivalent in Bundled mode (flow.json)

{

  "version": 4,

  "flows": {

    "default": {

      "config": { "platform": "web" },

      "sources": {

        "browser": {

          "package": "@walkeros/web-source-browser",

          "config": { "settings": { "pageview": true, "session": true } }

        }

      },

      "destinations": {

        // Your destinations here

      },

      "collector": { "run": true }

    }

  }

}
```

The mental model is the same (sources, collector, destinations), just with more control.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Common issues[​](#common-issues "Direct link to Common issues")

**Events not firing:** Check that walker.js loaded and configuration is valid.

**Missing events:** Ensure event queueing function is added before walker.js.

**Configuration not applied:** Verify `data-elbconfig` points to the correct object name.

## API reference[​](#api-reference "Direct link to API reference")

### Factory function[​](#factory-function "Direct link to Factory function")

```
createWalkerjs(config?: Config): Promise<Instance>
```

Creates a new walker.js instance with the provided configuration.

### Instance properties[​](#instance-properties "Direct link to Instance properties")

* `collector` - The walkerOS collector instance
* `elb` - Browser push function for event tracking

### Utility functions[​](#utility-functions "Direct link to Utility functions")

```
import { getAllEvents, getEvents, getGlobals } from '@walkeros/walker.js';

// Get all trackable events on the page
const events = getAllEvents();

// Get events for a specific element and trigger
const button = document.querySelector('button');
const clickEvents = getEvents(button, 'click');

// Get global properties from the page
const globals = getGlobals();
```

## Related documentation[​](#related-documentation "Direct link to Related documentation")

* **[Browser Source](https://www.walkeros.io/docs/sources/web/browser.md)** - Detailed DOM tracking capabilities
* **[Collector](https://www.walkeros.io/docs/collector.md)** - Event processing and routing
* **[Destinations](https://www.walkeros.io/docs/destinations.md)** - Available destination options
* **[DataLayer Source](https://www.walkeros.io/docs/sources/web/dataLayer.md)** - DataLayer integration details

Walker.js combines all these components into a single, easy-to-use package perfect for getting started with walkerOS quickly.