Skip to main content

🔧 theia Knowledge Base Integration Guide

This guide walks you through integrating the Knowledge Base extension into your theia-based IDE.

Table of Contents​

  1. Prerequisites
  2. Quick Integration (3 Steps)
  3. Detailed Setup
  4. Configuration
  5. Usage
  6. Troubleshooting
  7. Development
  8. Architecture

Prerequisites​

  • theia Application: Existing theia IDE (v1.45+)
  • Node.js: v18 or higher
  • Python: 3.8+ (for KB backend)
  • Knowledge Base API: Running on port 5175

Quick Integration (3 Steps)​

1️⃣ Add Extension to Dependencies​

In your theia application's package.json:

{
  "dependencies": {
    "@theia/core": "latest",
    "@theia/navigator": "latest",
    "@theia/monaco": "latest",
    "@theia/messages": "latest",
    "@coditect/theia-kb-extension": "file:../theia-kb-extension"
  }
}

2️⃣ Install and Build​

# From your theia app directory
npm install
npm run build

3️⃣ Start Services​

# terminal 1: Start KB API
cd knowledge-base-ui
npm run server

# terminal 2: Start theia
cd ../your-theia-app
npm start

✅ Access via: View → Knowledge Base

Detailed Setup​

Step 1: Verify Extension is Built​

cd theia-kb-extension
ls lib/browser/  # Should see compiled .js files

# If not built:
npm install
npm run build

For development, you can use npm link:

# In theia-kb-extension directory
npm link

# In your theia app directory
npm link @coditect/theia-kb-extension

Step 3: Configure theia Application​

Update package.json:​

{
  "name": "your-theia-app",
  "dependencies": {
    "@coditect/theia-kb-extension": "file:../theia-kb-extension"
  },
  "theiaExtensions": [
    "@coditect/theia-kb-extension"
  ]
}

Ensure Required theia Extensions:​

{
  "dependencies": {
    "@theia/core": "latest",
    "@theia/navigator": "latest",
    "@theia/workspace": "latest",
    "@theia/monaco": "latest",
    "@theia/messages": "latest",
    "@theia/scm": "latest",
    "@theia/editor": "latest"
  }
}

Step 4: Build theia Application​

# Clean build
npm run clean
npm install
npm run build

# Or if using yarn
yarn clean
yarn install
yarn build

Step 5: Configure API Endpoint (Optional)​

If KB API runs on a different host/port, create .theia/settings.json:

{
  "coditect.knowledgeBase.apiUrl": "http://localhost:5175/api",
  "coditect.knowledgeBase.timeout": 30000
}

Configuration​

Environment Variables​

# .env file in theia app root
KB_API_URL=http://localhost:5175/api
KB_API_TIMEOUT=30000

theia Preferences​

Access via: File → Preferences → Settings → Extensions → Knowledge Base

SettingDescriptionDefault
apiUrlKnowledge Base API endpointhttp://localhost:5175/api
timeoutAPI request timeout (ms)30000
defaultLimitDefault search result limit20
minRelevanceMinimum relevance threshold0.7

workspace Settings​

Create .theia/settings.json in your workspace:

{
  "coditect.knowledgeBase": {
    "apiUrl": "http://localhost:5175/api",
    "defaultCategories": ["debugging", "frontend"],
    "autoSearch": true,
    "searchOnSelection": true
  }
}

Usage​

1. Opening Knowledge Base View​

Via Menu:

  • View → Knowledge Base

Via Command Palette:

  • Ctrl/Cmd + Shift + P
  • Type: "Knowledge Base: Show"

Via Keyboard Shortcut (if configured):

  • Ctrl/Cmd + K, K

2. Searching​

Quick Search (Side Panel)​

  1. Click on Knowledge Base in sidebar
  2. Enter search query
  3. Press Enter or click Search
  1. View → Knowledge Base Search
  2. Use filters:
    • Categories
    • Status
    • Time window
    • Solution-only
    • Relevance threshold

Context Search from editor​

  1. Select text in editor
  2. Right-click → "Search in Knowledge Base"
  3. Or use: Edit → Search Knowledge Base

3. Applying Solutions​

When a search result contains a solution:

  1. Click "Apply" button on result
  2. Solution is inserted at current cursor position
  3. Or replaces selected text

4. Category Browsing​

In the Knowledge Base panel:

  • Click any category to instant-search
  • View document counts per category
  • Categories update in real-time

Troubleshooting​

Extension Not Appearing​

Check Installation:

# In theia app
npm list @coditect/theia-kb-extension

Verify Module Loading:

# Check console output on theia start
# Should see: "Knowledge Base extension activated"

Rebuild Completely:

npm run clean
rm -rf node_modules
npm install
npm run build

API Connection Failed​

Check API Server:

# Is API running?
curl http://localhost:5175/api/stats

# Check logs
cd knowledge-base-ui
npm run server

Verify Network:

  • No firewall blocking port 5175
  • Correct API URL in settings
  • CORS enabled on API server

Search Not Working​

Check Knowledge Base:

cd knowledge-base
python3 query_kb.py -i
> stats  # Should show document count

Rebuild KB if Empty:

python3 setup_chromadb.py

Widget Errors​

Console Errors:

  • Open Developer Tools: Help → Toggle Developer Tools
  • Check Console tab for errors
  • Look for injection errors

Common Fixes:

  1. Missing dependency injection
  2. API timeout - increase timeout setting
  3. Large results - reduce default limit

Development​

Extension Structure​

theia-kb-extension/
├── src/browser/
│   ├── kb-widget.tsx              # Main panel widget
│   ├── kb-search-widget.tsx       # Search widget
│   ├── kb-service.ts              # API service
│   ├── kb-contribution.ts         # Commands/menus
│   └── kb-extension-frontend-module.ts  # DI module
├── package.json
└── tsconfig.json

Adding Features​

New Command:​

// kb-contribution.ts
commands.registerCommand({
    id: 'kb.myNewCommand',
    label: 'My New KB Command'
}, {
    execute: () => this.kbService.doSomething()
});

New Menu Item:​

// kb-contribution.ts
menus.registerMenuAction(CommonMenus.VIEW, {
    commandId: 'kb.myNewCommand',
    label: 'My New Action'
});

Debugging​

  1. Enable Source Maps:

    // tsconfig.json
    "sourceMap": true

  2. Launch Configuration:

    // .vscode/launch.json
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch theia",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}"
    }

  3. Debug Logs:

    // Add to kb-service.ts
    console.log('[KB]', 'Debug message', data);

Testing​

# Unit tests
cd theia-kb-extension
npm test

# Integration test
npm run test:integration

Architecture​

Component Flow​

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  theia editor   │────▶│  KB Extension   │────▶│   KB API        │
│                 │     │                 │     │  (Port 5175)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                        │
         │                       │                        ▼
         ▼                       ▼                ┌─────────────────┐
┌─────────────────┐     ┌─────────────────┐     │  ChromaDB       │
│  User Selection │     │  KB Widgets     │     │  Vector Store   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Dependency Injection​

// Module registration
export default new ContainerModule(bind => {
    // Service
    bind(KnowledgeBaseService).toSelf().inSingletonScope();
    
    // Widgets
    bind(KnowledgeBaseWidget).toSelf();
    bind(WidgetFactory).toDynamicValue(ctx => ({
        id: KnowledgeBaseWidget.ID,
        createWidget: () => ctx.container.get(KnowledgeBaseWidget)
    }));
    
    // Contributions
    bind(CommandContribution).to(KnowledgeBaseContribution);
    bind(MenuContribution).to(KnowledgeBaseContribution);
});

API Integration​

// kb-service.ts
async search(params: SearchParams): Promise<SearchResult> {
    const response = await fetch(`${this.apiUrl}/search`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(params)
    });
    return response.json();
}

Best Practices​

1. Performance​

  • Debounce searches: Wait 300ms after typing
  • Limit results: Default to 20, max 50
  • Cache results: Store recent searches
  • Lazy load: Load categories on demand

2. User Experience​

  • Show loading states: Spinner during search
  • Handle errors gracefully: User-friendly messages
  • Preserve context: Remember filters/query
  • Keyboard shortcuts: For power users

3. Integration​

  • Follow theia patterns: Use DI, commands, contributions
  • Respect themes: Use theia CSS classes
  • Handle workspace changes: Clear cache on switch
  • Support offline: Graceful degradation

Advanced Configuration​

Custom Styling​

Create style/custom-kb.css:

/* Override KB widget styles */
.kb-widget {
    --kb-primary: var(--theia-brand-color0);
    --kb-background: var(--theia-editor-background);
}

.kb-search-result-item {
    border-color: var(--theia-border-color);
}

API Interceptors​

// Add to kb-service.ts
protected async request(url: string, options: RequestInit): Promise<Response> {
    // Add auth headers
    options.headers = {
        ...options.headers,
        'Authorization': `Bearer ${this.getAuthToken()}`
    };
    
    // Add telemetry
    const start = Date.now();
    const response = await fetch(url, options);
    console.log(`[KB] ${url} took ${Date.now() - start}ms`);
    
    return response;
}

Event Handling​

// Listen for workspace events
@inject(workspaceService)
protected readonly workspaceService: workspaceService;

@postConstruct()
protected init(): void {
    this.workspaceService.onworkspaceChanged(() => {
        this.clearCache();
        this.loadworkspaceSpecificData();
    });
}

Migration from Standalone​

If migrating from the standalone React app:

  1. Reuse Components: Extract React components
  2. Share Styles: Import CSS with adjustments
  3. Sync State: Use theia's state management
  4. Port Features: Commands instead of buttons

Resources​

  • Extension Source: /theia-kb-extension
  • API Documentation: /knowledge-base-ui/README.md
  • theia Docs: https://theia-ide.org/docs/
  • Support: File issues in project repository

Quick Commands Reference​

CommandDescriptionShortcut
kb.showShow Knowledge Base view-
kb.searchOpen search widgetCtrl+K K
kb.searchSelectionSearch selected textCtrl+K S
kb.refreshRefresh stats/categoriesF5 (in KB view)
kb.clearCacheClear search cache-

Last Updated: 2025-10-09 Version: 1.0.0