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 { createCollector } 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:

import { createSource, createDestination } from '@walkeros/core';

// Single big config file approach
const { elb } = await createCollector({
  sources: {
    browser: createSource(sourceBrowser, {
      settings: { scope: document.body },
    }),
  },
});

// Add destination with configuration
elb(
  'walker destination',
  createDestination(destinationGtag, {
    settings: {
      ga4: { measurementId: 'G-XXXXXXXXXX' },
    },
  }),
);

Breaking Changes

1. Unified Collector

• Single @walkeros/collector package works across all platforms
• Use createCollector() 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

Option 1: Traditional Configuration (Current)

elb('walker destination', destinationGtag, {
  settings: {
    ga4: { measurementId: 'G-XXXXXXXXXX' },
  },
});

Option 2: Using createSource and createDestination (New)

For a more elegant API and to avoid config side-effects in tests:

import { createSource, createDestination } from '@walkeros/core';

// Complete tracking setup in one config
const trackingConfig = {
  sources: {
    browser: createSource(sourceBrowser, {
      settings: { scope: document.body, session: true },
    }),
  },
};

const { elb } = await createCollector(trackingConfig);

elb(
  'walker destination',
  createDestination(destinationGtag, {
    settings: {
      ga4: { measurementId: 'G-XXXXXXXXXX' },
    },
  }),
);

Benefits of createSource and createDestination:

• Creates fresh instances (no config side-effects)
• Enables single-config-file setups describing entire tracking
• Maintains full type safety with proper config linking
• Consistent API pattern for sources and destinations
• No more { code, config } complexity

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 createCollector()
• 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 createCollector() function

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