Migration Guide

This guide helps you migrate between different versions of Trae and upgrade your extensions, configurations, and projects.

Overview

Trae provides migration tools and guides to help you:

• Upgrade from older versions to newer versions
• Migrate extensions and plugins
• Update configuration files and settings
• Convert legacy projects and workspaces
• Handle breaking changes and deprecated features
• Preserve custom configurations and data

Version Migration

Trae 2.x to 3.x

Breaking Changes

• API Changes: Several APIs have been updated with new signatures
• Configuration Format: Settings format has been modernized
• Extension System: New extension architecture with improved capabilities
• Plugin Interface: Updated plugin interface for better performance

Migration Steps

1. Backup Your Data

   # Backup your workspace
   cp -r ~/.trae ~/.trae-backup
   
   # Backup project configurations
   find . -name ".trae" -type d -exec cp -r {} {}.backup \;

2. Update Configuration Files

   // Old format (v2.x)
   {
     "editor": {
       "fontSize": 14,
       "theme": "dark"
     }
   }
   
   // New format (v3.x)
   {
     "editor.fontSize": 14,
     "workbench.colorTheme": "dark"
   }

3. Update Extensions

   # List installed extensions
   trae --list-extensions
   
   # Update all extensions
   trae --update-extensions
   
   # Reinstall incompatible extensions
   trae --reinstall-extensions

4. Migrate Custom Settings

   import { MigrationTool } from '@trae/migration';
   
   const migrator = new MigrationTool();
   
   // Migrate settings
   await migrator.migrateSettings({
     from: '2.x',
     to: '3.x',
     settingsPath: '~/.trae/settings.json'
   });
   
   // Migrate keybindings
   await migrator.migrateKeybindings({
     from: '2.x',
     to: '3.x',
     keybindingsPath: '~/.trae/keybindings.json'
   });

Trae 1.x to 2.x

Major Changes

• Workspace Format: New workspace file structure
• Theme System: Enhanced theming capabilities
• Language Support: Improved language server integration
• Debug Configuration: Updated debugging interface

Migration Process

1. Convert Workspace Files

   import { WorkspaceMigrator } from '@trae/migration';
   
   const migrator = new WorkspaceMigrator();
   
   // Convert workspace
   await migrator.convertWorkspace({
     source: './project.trae-workspace',
     target: './project.code-workspace',
     version: '2.x'
   });

2. Update Launch Configurations

   // Old format (v1.x)
   {
     "version": "0.1.0",
     "configurations": [
       {
         "name": "Launch",
         "type": "node",
         "program": "${workspaceRoot}/app.js"
       }
     ]
   }
   
   // New format (v2.x)
   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Launch",
         "type": "node",
         "program": "${workspaceFolder}/app.js",
         "console": "integratedTerminal"
       }
     ]
   }

Extension Migration

API Updates

Command Registration

// Old API (v2.x)
context.subscriptions.push(
  trae.commands.registerCommand('extension.myCommand', () => {
    // Command logic
  })
);

// New API (v3.x)
context.subscriptions.push(
  trae.commands.registerCommand('extension.myCommand', {
    handler: () => {
      // Command logic
    },
    enablement: 'editorHasSelection'
  })
);

Configuration Access

// Old API (v2.x)
const config = trae.workspace.getConfiguration('myExtension');
const value = config.get('setting');

// New API (v3.x)
const config = trae.workspace.getConfiguration();
const value = config.get('myExtension.setting');

Event Handling

// Old API (v2.x)
trae.workspace.onDidChangeTextDocument((event) => {
  // Handle change
});

// New API (v3.x)
trae.workspace.onDidChangeTextDocument((event) => {
  // Handle change with improved event data
}, null, context.subscriptions);

Extension Manifest Updates

// Old manifest (v2.x)
{
  "name": "my-extension",
  "version": "1.0.0",
  "engines": {
    "trae": "^2.0.0"
  },
  "activationEvents": [
    "onLanguage:javascript"
  ]
}

// New manifest (v3.x)
{
  "name": "my-extension",
  "version": "2.0.0",
  "engines": {
    "trae": "^3.0.0"
  },
  "activationEvents": [
    "onLanguage:javascript"
  ],
  "capabilities": {
    "virtualWorkspaces": true,
    "untrustedWorkspaces": {
      "supported": true
    }
  }
}

Configuration Migration

Settings Migration

import { SettingsMigrator } from '@trae/migration';

class SettingsMigrator {
  async migrateSettings(options: MigrationOptions): Promise<void> {
    const oldSettings = await this.loadSettings(options.from);
    const newSettings = this.transformSettings(oldSettings, options.to);
    await this.saveSettings(newSettings, options.to);
  }

  private transformSettings(oldSettings: any, targetVersion: string): any {
    const newSettings: any = {};
    
    // Transform editor settings
    if (oldSettings.editor) {
      newSettings['editor.fontSize'] = oldSettings.editor.fontSize;
      newSettings['editor.fontFamily'] = oldSettings.editor.fontFamily;
      newSettings['editor.tabSize'] = oldSettings.editor.tabSize;
    }
    
    // Transform workbench settings
    if (oldSettings.workbench) {
      newSettings['workbench.colorTheme'] = oldSettings.workbench.theme;
      newSettings['workbench.iconTheme'] = oldSettings.workbench.iconTheme;
    }
    
    // Transform extension settings
    if (oldSettings.extensions) {
      for (const [key, value] of Object.entries(oldSettings.extensions)) {
        newSettings[`extensions.${key}`] = value;
      }
    }
    
    return newSettings;
  }
}

Keybindings Migration

import { KeybindingsMigrator } from '@trae/migration';

class KeybindingsMigrator {
  async migrateKeybindings(options: MigrationOptions): Promise<void> {
    const oldKeybindings = await this.loadKeybindings(options.from);
    const newKeybindings = this.transformKeybindings(oldKeybindings);
    await this.saveKeybindings(newKeybindings, options.to);
  }

  private transformKeybindings(oldKeybindings: any[]): any[] {
    return oldKeybindings.map(binding => {
      // Update command names
      if (binding.command === 'workbench.action.files.openFile') {
        binding.command = 'workbench.action.files.openFileFolder';
      }
      
      // Update key combinations
      if (binding.key === 'ctrl+shift+p') {
        binding.key = 'cmd+shift+p';
      }
      
      return binding;
    });
  }
}

Data Migration

Workspace Data

import { WorkspaceDataMigrator } from '@trae/migration';

class WorkspaceDataMigrator {
  async migrateWorkspaceData(workspacePath: string): Promise<void> {
    const workspaceData = await this.loadWorkspaceData(workspacePath);
    
    // Migrate project settings
    if (workspaceData.settings) {
      workspaceData.settings = this.migrateProjectSettings(workspaceData.settings);
    }
    
    // Migrate launch configurations
    if (workspaceData.launch) {
      workspaceData.launch = this.migrateLaunchConfigurations(workspaceData.launch);
    }
    
    // Migrate tasks
    if (workspaceData.tasks) {
      workspaceData.tasks = this.migrateTasks(workspaceData.tasks);
    }
    
    await this.saveWorkspaceData(workspacePath, workspaceData);
  }

  private migrateProjectSettings(settings: any): any {
    // Transform project-specific settings
    const migratedSettings = { ...settings };
    
    // Update file associations
    if (settings.files?.associations) {
      migratedSettings['files.associations'] = settings.files.associations;
      delete migratedSettings.files;
    }
    
    return migratedSettings;
  }

  private migrateLaunchConfigurations(launch: any): any {
    return {
      ...launch,
      version: '0.2.0',
      configurations: launch.configurations.map((config: any) => ({
        ...config,
        program: config.program?.replace('${workspaceRoot}', '${workspaceFolder}'),
        console: config.console || 'integratedTerminal'
      }))
    };
  }
}

Extension Data

import { ExtensionDataMigrator } from '@trae/migration';

class ExtensionDataMigrator {
  async migrateExtensionData(extensionId: string): Promise<void> {
    const extensionData = await this.loadExtensionData(extensionId);
    
    // Migrate extension state
    if (extensionData.state) {
      extensionData.state = this.migrateExtensionState(extensionData.state);
    }
    
    // Migrate extension settings
    if (extensionData.settings) {
      extensionData.settings = this.migrateExtensionSettings(extensionData.settings);
    }
    
    await this.saveExtensionData(extensionId, extensionData);
  }

  private migrateExtensionState(state: any): any {
    // Transform extension state data
    const migratedState = { ...state };
    
    // Update state structure
    if (state.version === '1.0') {
      migratedState.version = '2.0';
      migratedState.data = this.transformStateData(state.data);
    }
    
    return migratedState;
  }
}

Migration Tools

CLI Migration Tool

# Install migration tool
npm install -g @trae/migration-cli

# Run migration
trae-migrate --from 2.x --to 3.x --workspace ./my-project

# Dry run (preview changes)
trae-migrate --from 2.x --to 3.x --workspace ./my-project --dry-run

# Migrate specific components
trae-migrate --from 2.x --to 3.x --settings-only
trae-migrate --from 2.x --to 3.x --extensions-only
trae-migrate --from 2.x --to 3.x --workspace-only

Programmatic Migration

import { MigrationManager } from '@trae/migration';

const migrationManager = new MigrationManager();

// Run full migration
await migrationManager.migrate({
  from: '2.x',
  to: '3.x',
  workspace: './my-project',
  backup: true,
  dryRun: false
});

// Run selective migration
await migrationManager.migrateSelective({
  from: '2.x',
  to: '3.x',
  components: ['settings', 'keybindings', 'extensions'],
  workspace: './my-project'
});

Troubleshooting

Common Issues

1. Extension Compatibility

   • Check extension compatibility with new version
   • Update or replace incompatible extensions
   • Report issues to extension authors

2. Configuration Conflicts

   • Review migrated settings for conflicts
   • Reset problematic settings to defaults
   • Manually adjust complex configurations

3. Data Loss Prevention

   • Always backup before migration
   • Verify migration results
   • Keep backups until migration is confirmed successful

Recovery Procedures

# Restore from backup
cp -r ~/.trae-backup ~/.trae

# Reset to defaults
trae --reset-settings
trae --reset-keybindings

# Reinstall extensions
trae --uninstall-all-extensions
trae --install-extensions-from-backup

Best Practices

1. Pre-Migration

   • Create complete backups
   • Document custom configurations
   • Test migration on non-production environments
   • Review breaking changes documentation

2. During Migration

   • Run dry-run first
   • Migrate incrementally
   • Verify each step
   • Keep detailed logs

3. Post-Migration

   • Test all functionality
   • Update documentation
   • Train team members on changes
   • Monitor for issues

Related Resources

• Version History - Detailed version information
• Extensions API - Extension development guide
• Settings API - Configuration management
• Workspace API - Workspace configuration
• Commands API - Command system updates