Migration Guide

LARC Migration Guide

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

• 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
0.x	1.0.x	No breaking changes
1.0.x	1.0.y	No changes needed (PATCH)
1.x	1.y	No changes needed (MINOR)
1.x	2.0	See guide below

---

Migrating from 0.x to 1.0.x

Good News: LARC 1.0 introduces zero breaking changes to the core APIs. Upgrade safely!

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)

Improved (Non-Breaking)

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

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

npm test

Step 3: Optional - Adopt New 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>
<!-- 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 });

Compatibility Notes

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.)

---

Migrating from 1.x to 2.0

Overview

LARC 2.0 is a major release with modular packages for better tree-shaking and smaller bundles.

Breaking Changes

Package Structure

Before (1.x):

npm install @larcjs/core

After (2.0):

# Core packages
npm install @larcjs/core-lite     # 9KB - Basic messaging
npm install @larcjs/core          # 40KB - Full featured
npm install @larcjs/core-routing  # +8KB - Message routing
npm install @larcjs/core-debug    # +3KB - Debug tools

Import Changes

Before (1.x):

import { PanClient, PanBus } from '@larcjs/core';

After (2.0):

// From core-lite (smaller bundle)
import { PanClient } from '@larcjs/core-lite';

// Or from full core (includes all features)
import { PanClient, PanBus } from '@larcjs/core';

Migration Steps

1. Choose your package:

   • @larcjs/core-lite - For most apps (9KB)
   • @larcjs/core - Full featured (40KB)

2. Update imports if using core-lite

3. Add optional packages as needed:

   npm install @larcjs/core-routing  # If you need routing
   npm install @larcjs/core-debug    # For development

4. Run tests

---

Package-Specific Migrations

@larcjs/core

Current Status (v2.0.x)

• Stability: HIGH - Core APIs are locked
• Breaking Changes: Package restructuring from 1.x
• Deprecations: None

@larcjs/ui

Current Status (v2.0.x)

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

---

Migration from Other Libraries

From Redux

Redux	LARC
Store	PAN Bus + Retained Messages
Actions	PAN Topics
Reducers	Provider Components
Selectors	pan-computed-state
Middleware	store.use()
DevTools	pan-inspector

From Context API

Context API	LARC
createContext()	PAN topic namespace
Provider	Provider components
useContext()	panClient.subscribe()

---

General Migration Best Practices

Before You Migrate

1. Read the Release Notes - Check CHANGELOG for breaking changes
2. Review Dependencies - npm outdated
3. Check Compatibility - See Browser-Compatibility

During Migration

1. Create a Feature Branch

   git checkout -b upgrade-larc-2.0

2. Update One Package at a Time

   npm install @larcjs/core@2.0.0
   npm test

3. Run Your Test Suite

4. Test in Development Environment

5. Monitor Deprecation Warnings

After Migration

1. Update Your Code - Replace deprecated APIs
2. Update Documentation
3. Deploy Gradually - Canary deployment recommended

---

Migration Checklist

Pre-Migration

• Read CHANGELOG.md for target version
• Read this migration guide
• Check browser compatibility requirements
• Create git feature branch
• Set up rollback plan

Migration

• Update package.json dependencies
• Run npm install
• Update code following migration guide
• Fix deprecation warnings
• Run test suite
• Test in development environment

Post-Migration

• Update documentation
• Deploy to staging environment
• Perform QA testing
• Monitor error logs
• Gradual rollout to production

---

FAQ

Do I need to migrate from 1.x to 2.0?

It's recommended for the smaller bundle sizes and modular packages. But 1.x code should work with minimal changes.

Will my 1.x code break in 2.0?

Most code will work. Main change is package restructuring for better tree-shaking.

Can I use core-lite with existing code?

Yes! Core-lite has the same API as the full core. Just install and update imports.

---

Getting Help

• Troubleshooting - Common issues and solutions
• GitHub Issues - Report migration problems
• GitHub Discussions - Ask questions