Skip to main content

ADR-014: Use Eclipse theia as IDE Foundation

Date: 2025-10-06 Status: Accepted Deciders: Development Team Tags: architecture, ide, foundation

Context​

Building a complete browser-based IDE from scratch would require:

  • File explorer implementation
  • editor integration (Monaco)
  • terminal implementation
  • Extension system
  • Settings management
  • Keybinding system
  • Workbench layout
  • Menu system

User Requirement: "is there a vs code javascript that works in the browser? do a web search of git hub and see what we can find so we do not have to totally build the whole ui from scratch. we want to leverage what but make sure that the licenses allow commercial reuse without fees"

Decision​

We will use Eclipse theia as the foundational framework instead of building the IDE from scratch.

Rationale​

Why Eclipse theia​

  1. License: EPL 2.0 (Eclipse Public License 2.0)

    • ✅ Free commercial use without fees
    • ✅ No proprietary constraints
    • ✅ Vendor-neutral (Eclipse Foundation)
    • ✅ No license costs ever

  2. VS Code Compatible:

    • Uses Monaco editor (same as VS Code)
    • Compatible with VS Code extensions via Open VSX
    • Similar UI/UX to VS Code
    • LSP (Language Server Protocol) support

  3. Browser + Desktop:

    • Runs natively in browser
    • Can be packaged as Electron app
    • WebSocket-based architecture

  4. Fully Open Source:

    • No proprietary parts
    • Hosted by Eclipse Foundation
    • TypeScript-based
    • Modular architecture

  5. Production Ready:

    • Used by Gitpod, Eclipse Che
    • Active development
    • Large community
    • Comprehensive documentation

vs Building from Scratch​

FeatureFrom ScratchEclipse theia
Development Time6-12 months1-2 months (customization)
MaintenanceHighLow (upstream updates)
VS Code ExtensionsNeed to implement✅ Built-in support
File ExplorerBuild it✅ Included
terminalIntegrate xterm.js✅ Included
SettingsBuild system✅ Included
KeybindingsImplement✅ Included
CostHigh labor costFREE

vs Other Options​

code-server (Coder):

  • ❌ Full VS Code (heavier)
  • ✅ MIT License
  • ❌ Less customizable

OpenVSCode Server:

  • ✅ Lighter than code-server
  • ✅ MIT License
  • ❌ Tied to Gitpod ecosystem

Eclipse theia:

  • ✅ Most flexible
  • ✅ Modular architecture
  • ✅ EPL 2.0 (commercial friendly)
  • ✅ Truly independent

Architecture Integration​

theia + Our Features​

Implementation​

Setup theia​

# Install theia
npm install @theia/core @theia/filesystem @theia/editor @theia/monaco @theia/terminal

# Or use theia Blueprint (pre-configured)
git clone https://github.com/eclipse-theia/theia-blueprint.git
cd theia-blueprint
yarn

Custom theia Extension​

// src/browser/llm-integration-contribution.ts
import { injectable } from '@theia/core/shared/inversify';
import { CommandContribution, CommandRegistry, MenuContribution, MenuModelRegistry } from '@theia/core/lib/common';

@injectable()
export class llmIntegrationContribution implements CommandContribution, MenuContribution {
  registerCommands(commands: CommandRegistry): void {
    commands.registerCommand({
      id: 'llm:chat',
      label: 'Chat with llm'
    }, {
      execute: async () => {
        // Open llm chat panel
        const llmService = this.getllmService();
        await llmService.openChatPanel();
      }
    });
  }

  registerMenus(menus: MenuModelRegistry): void {
    menus.registerMenuAction(['llm_menu'], {
      commandId: 'llm:chat',
      label: 'Chat with llm'
    });
  }
}

Multi-Session Extension​

// src/browser/session-contribution.ts
import { injectable, inject } from '@theia/core/shared/inversify';
import { ApplicationShell } from '@theia/core/lib/browser';

@injectable()
export class SessionContribution {
  @inject(ApplicationShell)
  protected readonly shell: ApplicationShell;

  async createSession(name: string): Promise<void> {
    // Create new session workspace
    const sessionId = generateId();

    // Open in new theia widget
    const widget = await this.createSessionWidget(sessionId, name);
    this.shell.addWidget(widget, { area: 'main' });
  }

  private async createSessionWidget(sessionId: string, name: string): Promise<Widget> {
    // Create isolated workspace for session
    return new SessionworkspaceWidget(sessionId, name);
  }
}

Package Configuration​

{
  "name": "az1ai-theia-ide",
  "version": "0.1.0",
  "dependencies": {
    "@theia/core": "^1.45.0",
    "@theia/filesystem": "^1.45.0",
    "@theia/editor": "^1.45.0",
    "@theia/monaco": "^1.45.0",
    "@theia/terminal": "^1.45.0",
    "@theia/preferences": "^1.45.0",
    "@theia/workspace": "^1.45.0"
  },
  "theiaExtensions": [
    {
      "frontend": "lib/browser/llm-integration-module"
    },
    {
      "frontend": "lib/browser/session-module"
    },
    {
      "frontend": "lib/browser/agent-module"
    }
  ]
}

Docker Integration​

# Dockerfile
FROM node:20-slim

WORKDIR /app

# Install theia dependencies
RUN apt-get update && apt-get install -y \
    git \
    python3 \
    make \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# Copy theia app
COPY package*.json ./
RUN yarn install

COPY . .
RUN yarn theia build

EXPOSE 3000

CMD ["yarn", "theia", "start", "/workspace", "--hostname=0.0.0.0"]

Customizations We'll Add​

1. llm Integration Panel​

// Custom panel for llm chat
export class llmChatPanel extends ReactWidget {
  // Integrate with LM Studio and Claude Code
}

2. Multi-Session Tabs​

// Top-level session management
export class SessionManager {
  // Create/switch/close sessions
}

3. Agent System Integration​

// Agent panel showing active agents
export class AgentPanel extends ReactWidget {
  // Display agent status, workflows
}

4. FoundationDB Integration​

// Replace theia's default file service
export class FDBFileService implements FileService {
  // Use FoundationDB for persistence
}

Migration Path​

Phase 1: Setup theia (Week 1)​

  1. Install theia Blueprint
  2. Customize branding (AZ1.AI logo, colors)
  3. Configure for Docker

Phase 2: Core Extensions (Week 2-3)​

  1. llm Integration extension
  2. MCP extension
  3. A2A extension

Phase 3: Advanced Features (Week 4-5)​

  1. Multi-session architecture
  2. Agent system
  3. FoundationDB integration

Phase 4: Polish (Week 6)​

  1. UI refinements
  2. Performance optimization
  3. Testing

Benefits​

Time Saved​

  • 6-12 months of development → 1-2 months customization
  • Focus on unique features (llm, agents, sessions)
  • Leverage battle-tested IDE framework

Cost Savings​

  • $0 licensing fees (EPL 2.0)
  • $0 royalties
  • $0 per-user costs
  • Free for commercial use

Technical Benefits​

  • Production-ready IDE framework
  • VS Code extension ecosystem
  • Active community support
  • Regular updates from Eclipse Foundation

Consequences​

Positive​

  • Massive development time savings
  • Professional IDE out of the box
  • Free commercial use (EPL 2.0)
  • VS Code extension compatible
  • Active Eclipse Foundation support

Negative​

  • Need to learn theia extension API
  • Some coupling to theia architecture
  • Must follow theia update cycle

Neutral​

  • TypeScript/Inversify dependency injection
  • Webpack-based build (can switch to Vite later)
  • Extension-based architecture

References​