theia Package Update Strategy

Last Updated: 2025-10-27 Status: ✅ ACTIVE - Syncing with theia-ide/browser

Overview

Our custom theia-app stays up-to-date with official theia IDE packages using the theia-ide git submodule as a reference.

What Changed (2025-10-27)

Added 42 New Packages

10 New AI Packages:

@theia/ai-anthropic - ✨ Direct Anthropic/Claude API
@theia/ai-claude-code - 🔥 KEY: Claude Pro integration without API keys
@theia/ai-google - Google Gemini support
@theia/ai-huggingface - HuggingFace models
@theia/ai-llamafile - Local LlamaFile (LM Studio alternative)
@theia/ai-mcp-server - Host MCP servers
@theia/ai-mcp-ui - MCP UI components
@theia/ai-scanoss - Security scanning
@theia/ai-terminal - AI-assisted terminal
@theia/ai-vercel-ai - Vercel AI SDK

32 Additional Feature Packages:

Real-time collaboration (@theia/collaboration)
Jupyter notebooks (@theia/notebook)
Dev containers (@theia/dev-container)
Remote development (@theia/remote)
Toolbar UI (@theia/toolbar)
Debugging (@theia/debug)
Search in workspace (@theia/search-in-workspace)
SCM/Git (@theia/scm)
And 24 more...

Before: 24 packages After: 66 packages Increase: +175% packages

Keeping Updated: 3 Methods

Method 1: Automated Script (Recommended)

Run quarterly or when theia releases new version:

./scripts/sync-theia-packages.sh

What it does:

Updates theia-ide submodule to latest
Extracts all @theia/* package versions from theia-ide/applications/browser/package.json
Updates theia-app/package.json with matching versions
Sorts dependencies alphabetically
Creates backup (theia-app/package.json.backup)

Output:

🔄 Syncing theia packages...
📥 Updating theia-ide submodule to latest...
   theia version: 1.65.1
🔍 Finding @theia/* packages...
   Found 66 @theia/* packages
   ✓ Updated @theia/ai-anthropic to ^1.65.1
   ✨ Added @theia/ai-claude-code: ^1.65.1
✅ Package sync complete!

Then:

cd theia-app
npm install
npm run prepare  # Test build
git add package.json
git commit -m "chore: Sync theia packages from theia-ide v1.65.1"

Method 2: Manual Comparison

When you want more control:

# 1. Check theia-ide version
cd theia-ide
git log -1 --oneline

# 2. Compare package versions
diff <(jq -r '.dependencies | keys[]' theia-ide/applications/browser/package.json | grep '@theia/' | sort) \
     <(jq -r '.dependencies | keys[]' theia-app/package.json | grep '@theia/' | sort)

# 3. See version differences
for pkg in $(jq -r '.dependencies | keys[]' theia-ide/applications/browser/package.json | grep '@theia/'); do
  IDE_VER=$(jq -r ".dependencies[\"$pkg\"]" theia-ide/applications/browser/package.json)
  APP_VER=$(jq -r ".dependencies[\"$pkg\"] // \"MISSING\"" theia-app/package.json)
  if [ "$IDE_VER" != "$APP_VER" ]; then
    echo "$pkg: $APP_VER → $IDE_VER"
  fi
done

# 4. Manually update package.json
vim theia-app/package.json

Method 3: NPM Outdated Check

Check for newer versions on npm:

cd theia-app
npm outdated | grep @theia/

# Update specific package
npm install @theia/ai-claude-code@latest --save

# Update all @theia/* packages
npm update @theia/*

Update Schedule

Frequency	Method	Use Case
Quarterly	Automated script	Sync with official theia IDE releases
Monthly	NPM outdated	Check for patch/security updates
On demand	Manual comparison	Before major feature work
After theia release	Automated script	Stay current with upstream

theia Release Cycle

theia IDE releases: ~Every 4-6 weeks Watch for: https://github.com/eclipse-theia/theia-ide/releases

Notification Setup:

# Watch theia-ide releases
cd theia-ide
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
gh repo set-default eclipse-theia/theia-ide
gh release list --limit 5

# Or set up GitHub notifications
# Go to: https://github.com/eclipse-theia/theia-ide
# Click: Watch > Custom > Releases

Version Strategy

Our approach: Use caret ranges (^1.65.0) for flexibility

{
  "dependencies": {
    "@theia/core": "^1.65.0"  // Allows 1.65.x, but not 1.66.0
  }
}

Why:

✅ Get patch fixes automatically (1.65.1, 1.65.2)
✅ Avoid breaking changes (major/minor blocked)
✅ Compatible with official theia IDE

theia IDE approach: Exact versions (1.65.1)

{
  "dependencies": {
    "@theia/core": "1.65.1"  // Exact, no automatic updates
  }
}

If you want exact versions (production stability):

# Convert ^ to exact versions
jq '.dependencies |= (to_entries | map(.value |= ltrimstr("^")) | from_entries)' theia-app/package.json > tmp.json
mv tmp.json theia-app/package.json

Testing After Updates

Always test after package updates:

# 1. Clean install
cd theia-app
rm -rf node_modules package-lock.json
npm install

# 2. Build
npm run prepare

# 3. Test locally
npm start
# Visit: http://localhost:3000

# 4. Check AI features work
# - Test @theia/ai-claude-code (Claude Pro integration)
# - Test @theia/ai-anthropic (Anthropic API)
# - Test @theia/ai-mcp (Model Context Protocol)
# - Test @theia/ai-terminal (AI terminal commands)

# 5. Docker build test
cd ..
docker build -f dockerfile.combined-fixed --target theia-builder .

Rollback Strategy

If update breaks something:

# 1. Restore backup
mv theia-app/package.json.backup theia-app/package.json

# 2. Or git revert
git checkout HEAD -- theia-app/package.json
cd theia-app
npm install

# 3. Or specific package downgrade
npm install @theia/ai-claude-code@1.65.0 --save

CI/CD Integration

Automated monthly checks (add to .github/workflows/theia-sync.yml):

name: Check theia Package Updates

on:
  schedule:
    - cron: '0 0 1 * *'  # Monthly on 1st
  workflow_dispatch:     # Manual trigger

jobs:
  check-updates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

      - name: Update theia-ide submodule
        run: |
          cd theia-ide
          git checkout main
          git pull origin main

      - name: Check for package differences
        run: |
          ./scripts/sync-theia-packages.sh
          if git diff --quiet theia-app/package.json; then
            echo "No updates needed"
          else
            echo "Updates available!"
            git diff theia-app/package.json
          fi

      - name: Create PR if updates found
        uses: peter-evans/create-pull-request@v5
        with:
          title: "chore: Sync theia packages from theia-ide"
          body: "Automated package sync from theia-ide submodule"
          branch: theia-package-sync

Key Packages to Watch

Critical for features:

@theia/ai-claude-code - Claude Pro integration (your main value prop)
@theia/ai-mcp - Model Context Protocol
@theia/ai-anthropic - Direct Anthropic API
@theia/collaboration - Real-time collaboration
@theia/remote - Remote development

Breaking changes most likely in:

@theia/core - Core framework
@theia/ai-core - AI framework
@theia/plugin-ext - Plugin system

Documentation

After each major update, document:

theia version updated from/to
New packages added
Breaking changes encountered
Configuration changes needed
Test results

Template:

## Update Log: [DATE]

**theia Version**: 1.65.0 → 1.66.0
**Packages Added**: @theia/ai-new-feature
**Breaking Changes**: None
**Config Changes**: Updated ai.claude-code.cliPath
**Tests**: ✅ All passing
**Deployment**: ✅ Successful

Quick Reference

# Check current versions
jq '.dependencies | to_entries | .[] | select(.key | startswith("@theia/")) | "\(.key): \(.value)"' theia-app/package.json

# Count packages
jq '.dependencies | to_entries | .[] | select(.key | startswith("@theia/")) | .key' theia-app/package.json | wc -l

# Find specific package
jq '.dependencies["@theia/ai-claude-code"]' theia-app/package.json

# Sync packages (automated)
./scripts/sync-theia-packages.sh

# Manual update
cd theia-app
npm install @theia/PACKAGE@version --save

Summary

✅ Added 42 new packages from theia-ide ✅ Automated sync script created ✅ Quarterly update schedule recommended ✅ CI/CD integration ready ✅ Rollback strategy documented

Next update: ~January 2026 (or when theia 1.66.0 releases)

Overview​

What Changed (2025-10-27)​

Added 42 New Packages​

Keeping Updated: 3 Methods​

Method 1: Automated Script (Recommended)​

Method 2: Manual Comparison​

Method 3: NPM Outdated Check​

Update Schedule​

theia Release Cycle​

Version Strategy​

Testing After Updates​

Rollback Strategy​

CI/CD Integration​

Key Packages to Watch​

Documentation​

Quick Reference​

Summary​