Migration Guide: From @elbwalker to @walkerOS

This guide helps you migrate from the old elbwalker packages to the new walkerOS packages.

Quick Reference

Core Package Changes

• @elbwalker/walker.js → @walkeros/collector + @walkeros/web-source-browser
• @elbwalker/types + @elbwalker/utils → @walkeros/core
• @elbwalker/destination-web-* → @walkeros/web-destination-*
• @elbwalker/destination-node-* → @walkeros/server-destination-*

Step-by-Step Migration

1. Update Dependencies

Before:

{
  "dependencies": {
    "@elbwalker/walker.js": "^2.0.0",
    "@elbwalker/destination-web-google-ga4": "^2.0.0"
  }
}

After:

{
  "dependencies": {
    "@walkeros/collector": "^0.0.7",
    "@walkeros/web-source-browser": "^0.0.7",
    "@walkeros/web-destination-gtag": "^0.0.7"
  }
}

2. Update Imports

Before:

import { Walkerjs } from '@elbwalker/walker.js';
import { destinationGoogleGA4 } from '@elbwalker/destination-web-google-ga4';
import type { WalkerOS } from '@elbwalker/types';

After:

import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';
import { destinationGtag } from '@walkeros/web-destination-gtag';
import type { WalkerOS } from '@walkeros/core';

3. Update Function Calls

Before:

const walker = Walkerjs({
  destinations: [destinationGoogleGA4],
});

After:

const { elb } = await startFlow({
  sources: {
    browser: {
      code: sourceBrowser,
      config: {
        settings: { scope: document.body },
      },
    },
  },
  destinations: {
    gtag: {
      code: destinationGtag,
      config: {
        settings: {
          ga4: { measurementId: 'G-XXXXXXXXXX' },
        },
      },
    },
  },
});

Breaking Changes

1. Unified Collector

• Single @walkeros/collector package works across all platforms
• Use startFlow() instead of Walkerjs() or createSourceNode()

2. Modular Sources

• DOM tracking is now @walkeros/web-source-browser
• Import and initialize sources separately

3. Core Package Merger

• All types and utilities now come from @walkeros/core
• Update all import statements accordingly

4. Google Destinations Unified

• GA4, Google Ads, and GTM are now unified in @walkeros/web-destination-gtag
• Configure all Google services through a single destination

Destination Configuration Patterns

Unified Configuration Approach

Configure all sources and destinations in a single startFlow call:

const { elb } = await startFlow({
  sources: {
    browser: {
      code: sourceBrowser,
      config: {
        settings: { scope: document.body, session: true },
      },
    },
  },
  destinations: {
    gtag: {
      code: destinationGtag,
      config: {
        settings: {
          ga4: { measurementId: 'G-XXXXXXXXXX' },
        },
      },
    },
  },
});

Benefits:

• Single configuration describing entire tracking setup
• Full type safety with proper config linking
• No manual destination registration needed
• Clean separation between code and configuration

Migration Checklist

Package Dependencies

• Remove old @elbwalker/* packages
• Add @walkeros/collector
• Add required sources and destinations
• Add @walkeros/core for custom implementations

Code Updates

• Update all imports to new packages
• Replace collector initialization with startFlow()
• Update type imports to use @walkeros/core
• Test functionality after migration

Common Issues

"Cannot find module @walkeros/web-collector"
Solution: Use @walkeros/collector + @walkeros/web-source-browser

"elb is not defined"
Solution: elb is returned by startFlow() function

TypeScript cannot find types
Solution: Import types from @walkeros/core

data-elbaction vs data-elbactions

Breaking Change in @walkeros packages

The behavior of data-elbaction has changed to improve performance and provide more precise entity targeting:

• @elbwalker behavior: data-elbaction applied to all entities in the DOM hierarchy
• @walkeros behavior: data-elbaction applies to nearest entity only

Migration Strategy

Option 1: Keep Current Behavior (Recommended for migration)

Replace data-elbaction with data-elbactions to maintain the same behavior:

<!-- Before (@elbwalker) -->
<div data-elb="parent">
  <div data-elb="child" data-elbaction="click:action">
    <!-- Triggered both parent and child entities -->
  </div>
</div>

<!-- After (@walkeros) - Same behavior -->
<div data-elb="parent">
  <div data-elb="child" data-elbactions="click:action">
    <!-- Triggers both parent and child entities -->
  </div>
</div>

Option 2: Use New Behavior (Recommended for new projects)

Use data-elbaction for more precise, performance-optimized tracking:

<!-- @walkeros - New behavior -->
<div data-elb="parent">
  <div data-elb="child" data-elbaction="click:action">
    <!-- Only triggers child entity -->
  </div>
</div>

When to Use Each

Use data-elbaction (nearest entity) when:

• You want precise tracking of only the specific entity
• Performance is critical (fewer events)
• Implementing new features

Use data-elbactions (all entities) when:

• Migrating from @elbwalker and need same behavior
• You need context from parent entities
• Analytics requires full DOM hierarchy

Tagger API

The tagger also provides both methods:

// Nearest entity only (data-elbaction)
tagger().action('click', 'select').get();

// All entities (data-elbactions)
tagger().actions('click', 'select').get();

visible vs impression Triggers

Breaking Change in @walkeros packages

The visibility trigger names have been updated to better reflect their behavior:

• visible trigger: Now fires multiple times when element re-enters viewport (was visibles)
• impression trigger: Fires once only when element first becomes visible (was visible)

Migration Strategy

Option 1: Update Trigger Names (Recommended)

Update your HTML to use the new trigger names:

<!-- Before (@elbwalker and early @walkeros) -->
<div data-elbaction="visible:view">Single fire</div>
<div data-elbaction="visibles:track">Multiple fires</div>

<!-- After (@walkeros current) -->
<div data-elbaction="impression:view">Single fire</div>
<div data-elbaction="visible:track">Multiple fires</div>

Option 2: Understand the Behavior Change

If you keep using the old names, understand the behavior has changed:

• Old visible behavior (single-fire) → Now use impression
• Old visibles behavior (multiple-fire) → Now use visible

When to Use Each

Use impression trigger when:

• You want to track when content is first seen
• Measuring ad impressions or content views
• One-time engagement metrics

Use visible trigger when:

• You want to track repeated interactions
• Measuring scroll behavior or re-engagement
• Analytics requires multiple visibility events

Tagger API

The tagger supports both trigger types:

// Single impression (fires once)
tagger().action('impression', 'view').get();

// Multiple visibility (fires each time visible)
tagger().action('visible', 'track').get();