Skip to main content

Migration Guide

How to upgrade your vertical application when the Vertical Template is updated.

Version Compatibility​

Template VersionNode.jsNext.js@enterpriseaigroup/client
2.x18+15+2.x
1.x18+14+1.x

Migration Process​

Step 1: Check Current Version​

# Check your current template version
cat package.json | grep version

# Check client package version
cat packages/client/package.json | grep version

Step 2: Review Release Notes​

Before upgrading, review the CHANGELOG for:

  • Breaking changes
  • New features
  • Deprecated APIs
  • Required migration steps

Step 3: Create a Backup Branch​

git checkout -b backup/pre-migration
git push origin backup/pre-migration
git checkout main

Step 4: Update Dependencies​

# Update all dependencies
npm update

# Or update specific packages
npm update @enterpriseaigroup/client

Step 5: Run Migration Scripts (if provided)​

# Check for migration scripts
ls scripts/migrations/

# Run migration script for specific version
npx tsx scripts/migrations/v2.0.0.ts

Common Migration Scenarios​

Migrating Tenant Configurations​

When the EAIConfig schema changes:

  1. Check for TypeScript errors

    npx tsc --noEmit

  2. Update tenant configs to match new schema:

    // Before (v1.x)
    export const config: EAIConfig = {
      tenantId: 'my-tenant',
      theme: {
        primaryColor: '#6366f1',
      },
    };

    // After (v2.x) - example with new required field
    export const config: EAIConfig = {
      tenantId: 'my-tenant',
      displayName: 'My Tenant',  // New required field
      theme: {
        primaryColor: '#6366f1',
      },
    };

  3. Validate all configs:

    npm run validate-config

Migrating Store Slices​

When store slice structure changes:

  1. Update initialState to match new shape
  2. Update storeBindings in component configs
  3. Clear persisted state (if schema changed): 
    // In browser console or code
    sessionStorage.clear();

Migrating Components​

When component props change:

  1. Check ComponentRegistry for renamed components
  2. Update props in tenant configs: 
    // Before
    { component: 'OldComponentName', props: { oldProp: true } }

    // After
    { component: 'NewComponentName', props: { newProp: true } }

Migrating API Routes​

When API route patterns change:

  1. Update route files to new structure
  2. Update middleware usage
  3. Test all endpoints: 
    npm run test:api

Breaking Changes by Version​

v2.0.0 (Example)​

Breaking Changes:

  • EAIConfig.name renamed to EAIConfig.displayName
  • useStore hook renamed to useStoreValue
  • Removed deprecated fetchWithAuth - use client package instead

Migration Steps:

  1. Find and replace name: with displayName: in tenant configs
  2. Find and replace useStore( with useStoreValue( in components
  3. Replace fetchWithAuth calls with client package methods

Automated Migration:

# Run the v2 migration script
npx tsx scripts/migrations/v2.0.0.ts

Handling Merge Conflicts​

When pulling template updates creates conflicts:

Config Files​

# Keep your tenant configs, update types
git checkout --ours src/eai.config/tenants/
git checkout --theirs src/eai.config/types.ts

Package Dependencies​

# Accept both and resolve manually
git checkout --theirs package.json
npm install

Environment Variables​

# Compare with example
diff .env.local .env.example

# Add any new required variables

Rollback Procedure​

If migration fails:

# 1. Restore from backup branch
git checkout backup/pre-migration

# 2. Or revert specific commits
git revert HEAD~3..HEAD

# 3. Clear any corrupted state
rm -rf node_modules
rm -rf .next
npm install

# 4. Restart development
npm run dev

Testing After Migration​

Automated Tests​

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

Manual Verification Checklist​

  • Application starts without errors
  • All tenant configs load correctly
  • Authentication flow works
  • API calls succeed
  • Store persistence works
  • All pages render correctly
  • No console errors in browser

Getting Help​

If you encounter issues during migration:

  1. Check Troubleshooting for common issues
  2. Review Architecture Decision Records for context
  3. Open an issue on GitHub