LARC Migration Guide

Introduction

This guide helps you migrate between major versions of LARC packages. LARC follows Semantic Versioning, which means:

• PATCH updates (1.0.x) - Safe to update, no changes needed
• MINOR updates (1.x.0) - Safe to update, new features are opt-in
• MAJOR updates (x.0.0) - May require code changes

Quick Migration Index

| From Version | To Version | Migration Needed | Read Section | |--------------|------------|------------------|--------------| | 0.x | 1.0.x | ✅ No breaking changes | 0.x → 1.0 | | 1.0.x | 1.0.y | ✅ No changes needed | N/A (PATCH update) | | 1.x | 1.y | ✅ No changes needed | N/A (MINOR update) | | 1.x | 2.0 | ⚠️ Not released yet | N/A |

Migrating from 0.x to 1.0.x

Overview

What Changed in 1.0

#### Added (Non-Breaking)

• Component autoload system (opt-in)
• Router and navigation components
• WebSocket bridge component
• IndexedDB bridge component
• New UI components
• Comprehensive test suite (80%+ coverage)
• Performance benchmarks (300k+ msg/sec)
• Production documentation

• Enhanced error handling
• Better memory management
• Improved TypeScript support
• Extended browser compatibility documentation

• PAN bus delivery with document listeners
• Message delivery race conditions
• Path resolution in autoloader
• Retained message subscription loop

Migration Steps

#### Step 1: Update Package Version

# npm
npm install @larcjs/core@^1.0.0

# yarn
yarn add @larcjs/core@^1.0.0

# pnpm
pnpm add @larcjs/core@^1.0.0

#### Step 2: Test Your Application

Even though there are no breaking changes, run your test suite:

npm test

#### Step 3: Optional - Adopt New Features

Consider adopting these new 1.0 features:

##### Autoloader (Recommended)

<!-- Before (0.x): Manual imports -->
<script type="module">
  import './components/pan-bus.mjs';
  import './components/pan-client.mjs';
</script>

<!-- After (1.0): Automatic loading -->
<script type="module">
  import '@larcjs/core/pan.mjs';
</script>
<pan-bus></pan-bus>
<pan-client></pan-client>
<!-- Components load automatically when needed -->

##### Enhanced Client API

// Before (0.x): Still works in 1.0
const client = new PanClient();
await client.ready();

// After (1.0): New convenience methods
const data = await client.request('user.get', { id: 123 }, { timeout: 5000 });
const retained = await client.retained(['app.state.*']);

Compatibility Notes

#### What Remains Compatible

✅ All core APIs unchanged:

• PanBus component and configuration
• PanClient methods (publish, subscribe, request)
• PAN message envelope format
• Topic naming conventions
• CustomEvent names (pan:publish, pan:deliver, etc.)
• Configuration via attributes and window.panAutoload

// 0.x code still works perfectly in 1.0
document.addEventListener('pan:deliver', (e) => {
  const { topic, data } = e.detail;
  // This still works exactly as before
});

document.dispatchEvent(new CustomEvent('pan:publish', {
  detail: { topic: 'test.topic', data: { message: 'hello' } },
  bubbles: true
}));

#### What's New (Opt-In)

The following features are new in 1.0 but completely opt-in:

• Autoloader: Only activates if you import pan.mjs
• Router: Only if you use component
• WebSocket bridge: Only if you use
• IndexedDB bridge: Only if you use

Known Issues

Rollback Plan

If you encounter issues (unlikely), rolling back is simple:

# Rollback to 0.x
npm install @larcjs/core@0.1.0

# Or pin to last working version
npm install @larcjs/core@3.0.1

No code changes needed for rollback - APIs are fully compatible.

Migrating from 1.x to 2.0

LARC 2.0 has not been released yet. When it is, this section will document:

• Breaking changes introduced
• Step-by-step migration instructions
• Deprecation timeline for old APIs
• Automated migration tools (if available)

• Watch the GitHub releases
• Review CHANGELOG.md for release notes
• Check SEMVER.md for versioning policy

Package-Specific Migrations

@larcjs/core

#### Current Status (v1.0.x)

• Stability: HIGH - Core APIs are locked
• Breaking Changes: None since 1.0.0
• Deprecations: None

@larcjs/ui

#### Current Status (v1.0.x)

• Stability: MEDIUM - Components evolve more frequently
• Breaking Changes: None since 1.0.0
• Deprecations: None

• All UI components follow the same core messaging patterns
• Component tag names are stable once released
• New components added in MINOR versions (backward compatible)

General Migration Best Practices

Before You Migrate

npm outdated

During Migration

git checkout -b upgrade-larc-2.0

# Update core first
   npm install @larcjs/core@3.0.1
   npm test

   # Then update UI
   npm install @larcjs/ui@3.0.1
   npm test

npm test
   npm run test:integration

// Look for warnings in console
   console.warn('oldMethod() is deprecated, use newMethod()');

After Migration

Breaking Change Reference

Format

Each breaking change will be documented using this format:

#### Change Title

• Description of the breaking change
• Why the change was made

// Old API that no longer works

// New API to use instead

Example (Template for Future Releases)

#### Renamed PanClient.subscribe() to PanClient.on()

• subscribe() method renamed to on() for consistency with EventEmitter pattern
• unsubscribe() renamed to off()

const client = new PanClient();
const unsub = client.subscribe('user.*', (msg) => {
  console.log(msg.data);
});

// Later...
unsub();

const client = new PanClient();
const off = client.on('user.*', (msg) => {
  console.log(msg.data);
});

// Later...
off();

# Run migration script (if provided)
npx @larcjs/migrate 1.x-to-2.x

Deprecation Timeline

Current Deprecations

How Deprecations Work

When an API is deprecated, this section will show:

| API | Deprecated In | Removed In | Replacement | Migration Guide | |-----|---------------|------------|-------------|-----------------| | (none yet) | - | - | - | - |

| API | Deprecated In | Removed In | Replacement | Migration Guide | |-----|---------------|------------|-------------|-----------------| | subscribe() | 1.5.0 | 3.0.1 | on() | Link |

Automated Migration Tools

Current Tools

Future Tools

When LARC 2.0 is released with breaking changes, we plan to provide:

# Automated migration (planned for 2.0)
npx @larcjs/migrate 1.x-to-2.x

# Options
npx @larcjs/migrate 1.x-to-2.x --dry-run  # Preview changes
npx @larcjs/migrate 1.x-to-2.x --interactive  # Choose which changes to apply

Version-Specific Guides

0.x → 1.0.x ✅ COMPLETE

1.x → 2.0 ⚠️ NOT RELEASED

Getting Help

Migration Support

If you encounter issues during migration:

**Title:** Migration issue: [describe problem]

   **Migrating from:** 1.x.x
   **Migrating to:** 2.0.0

   **Error:**
   [paste error message]

   **Code:**
   [paste relevant code]

   **Expected:** What you expected to happen
   **Actual:** What actually happened

Version Support Policy

• Current MAJOR: Full support (bug fixes, security updates, features)
• Previous MAJOR: Critical bug fixes and security updates for 6 months
• Older versions: Community support only

• v1.x: Full support ✅
• v0.x: Critical fixes for 6 months (until May 2025) ⏰
• Earlier: Community only ⚠️

Migration Checklist

Use this checklist when performing any major version migration:

Pre-Migration

• [ ] Read CHANGELOG.md for target version
• [ ] Read this migration guide
• [ ] Check browser compatibility requirements
• [ ] Review deprecation notices
• [ ] Create git feature branch
• [ ] Backup production database (if applicable)
• [ ] Set up rollback plan

Migration

• [ ] Update package.json dependencies
• [ ] Run npm install
• [ ] Run automated migration tools (if available)
• [ ] Update code following migration guide
• [ ] Fix deprecation warnings
• [ ] Run test suite
• [ ] Test in development environment
• [ ] Test critical user flows manually

Post-Migration

• [ ] Update documentation
• [ ] Deploy to staging environment
• [ ] Perform QA testing
• [ ] Monitor error logs
• [ ] Canary deployment (5% traffic)
• [ ] Gradual rollout to 100%
• [ ] Monitor performance metrics
• [ ] Update internal runbooks

FAQ

Do I need to migrate from 0.x to 1.0?

• 80%+ test coverage
• Performance benchmarks (300k+ msg/sec)
• Production-ready documentation
• Security audit completed
• New opt-in features

Will my 0.x code break in 1.0?

How long will 0.x be supported?

Can I use new 1.0 features in 0.x?

What if I find a breaking change not documented here?

How do I stay informed about upcoming breaking changes?

• Watch GitHub Releases
• Subscribe to deprecation warnings in your console
• Join GitHub Discussions
• Read CHANGELOG.md with each update

Document History

| Version | Date | Changes | |---------|------|---------| | 1.0 | Nov 24, 2024 | Initial migration guide with 0.x → 1.0.x guide |

See Also

• Semantic Versioning Commitment
• API Reference
• Troubleshooting Guide
• Production Deployment Guide
• CHANGELOG