CLAUDE.md · eclipse-theia/theia

Sections

1. Development Commands
2. Architecture
3. Key Patterns
4. Technical Requirements
5. Commits, Issues, and Pull Requests

First lines (shown under the repo's EPL-2.0 license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

**Essential commands:** (use `npm`, not `yarn`, for all package management and scripts)
- `npm install` - Install dependencies (runs `theia-patch`, `compute-references`, and lerna `afterInstall` hooks)
- `npm run build:browser` - Builds all packages + bundles Browser example app (preferred during development)
- `npm run compile` - Compile TypeScript only (uses `tsc --build` with project references)
- `npm run lint` - Run ESLint across all packages
- `npm run lint:fix` - Run ESLint with auto-fix
- `npm run test` - Run all tests

**Important:** `npm run compile` only compiles TypeScript. Before UI testing, you must also run `npm run build:browser` to bundle the frontend — otherwise the running browser app won't include your latest changes. Bundling runs via `theia build` (in `@theia/cli` / `application-manager`) and always uses **esbuild**. The configuration files of each app (`esbuild.mjs` and the `gen-esbuild.*.mjs` it imports) are generated by `BundlerGenerator` in `dev-packages/application-manager`.

**Application commands:**
- `npm run start:browser` - Start browser example at localhost:3000
- `npm run start:electron` - Start electron application
- `npm run watch` - Watch mode for development (browser + electron concurrently)

**Package-specific:**
- `npx lerna run compile --scope @theia/package-name` - Build specific package
- `npx lerna run test --scope @theia/package-name` - Test specific package
- `npx lerna run watch --scope @theia/package-name --include-filtered-dependencies --parallel` - Watch package with dependencies

**Running a single test file (after compile):**
- `npx mocha ./packages/core/lib/browser/some-file.spec.js`

**Test infrastructure:** Tests use Mocha + NYC (Istanbul) for coverage. Config at `configs/mocharc.yml` and `configs/nyc.json`. Each package's `npm test` runs via the `theiaext test` wrapper defined in `dev-packages/private-ext-scripts`, which executes `nyc mocha --config ../../configs/mocharc.yml "./lib/**/*.*spec.js"`.

## Architecture

**Monorepo Structure:**
- Lerna-managed monorepo
- `/packages/` - Runtime packages (core + extensions)
- `/dev-packages/` - Development tooling (application-manager, cli, eslint-plugin, ext-scripts)
- `/examples/` - Sample applications (browser, electron, browser-only, playwright)
- `/configs/` - Shared config files (tsconfig, eslint, mocha, nyc)

**Platform-specific code organization (per package):**
- `src/common/` - Shared JavaScript APIs (runs everywhere)
- `src/browser/` - Browser/DOM APIs (InversifyJS DI container for frontend)
- `src/node/` - Node.js APIs (InversifyJS DI container for backend)
- `src/electron-browser/` - Electron renderer process
- `src/electron-main/` - Electron main process

**Extension entry points** are declared in each package's `package.json` under `theiaExtensions`:

```json
"theiaExtensions": [{
  "frontend": "lib/browser/editor-frontend-module",
  "backend": "lib/node/editor-backend-module"
}]
```

**Extension System:**
- Dependency Injection via InversifyJS (property injection preferred over constructor injection)
- Contribution Points pattern for extensibility (CommandContribution, MenuContribution, KeybindingContribution, FrontendApplicationContribution, etc.)
- Three extension types: Theia extensions (build-time), VS Code extensions (runtime), Theia plugins (runtime)

## Key Patterns

For more information also look at:
- @doc/coding-guidelines.md
- @doc/Testing.md
- @doc/Plugin-API.md (VS Code extension plugin API)
- @AGENTS.md (practical patterns for contributions, widgets, commands, preferences, plugin API, styling)

Read on demand (not auto-loaded) — consult when the task calls for it:
- [doc/code-organization.md](doc/code-organization.md) — platform import rules; consult when adding cross-platform imports.
- [doc/vscode-usage.md](doc/vscode-usage.md) — rules for exposing Monaco/VS Code internals from Theia packages.
- [doc/api-management.md](doc/api-management.md) — API stability lifecycle.
- [doc/api-testing.md](doc/api-testing.md) — API integration testing (vs. unit tests in `Testing.md`).
- [doc/pull-requests.md](doc/pull-requests.md) — PR / review checklist.
- [doc/Developing.md](doc/Developing.md) — full build/setup details.
- [doc/Migration.md](doc/Migration.md) — adopter-facing breaking-change notes.
- [doc/runtime-policy.md](doc/runtime-policy.md) / [doc/Publishing.md](doc/Publishing.md) — Node/Electron support and release process.
- [doc/lockfile-maintenance.md](doc/lockfile-maintenance.md) — `allowScripts` upkeep and platform-specific entries in `package-lock.json`; consult before committing lockfile changes.

**Code Style:**
- 4 spaces indentation, single quotes, `undefined` over `null`
- PascalCase for types/enums, camelCase for functions/variables
- Arrow functions preferred, explicit return types required
- Property injection over constructor injection, `@postConstruct()` for initialization

**File Naming:**
- kebab-case for files (e.g., `document-provider.ts`)
- File name matches main exported type
- Platform folders follow strict dependency rules (browser cannot import node, etc.)

**Architecture Patterns:**
- Main-Ext pattern for plugin API (browser Main ↔ plugin host Ext, communicating via RPC)
- Services as classes with DI, avoid exported functions (functions can't be overridden)
- `ContributionProvider` instead of `@multiInject` for collecting multiple implementations
- Use `bindRootContributionProvider` (not `bindContributionProvider`) when binding contribution providers in top-level modules. `bindContributionProvider` retains a reference to whichever child container first resolves it, causing memory leaks. Only use `bindContributionProvider` when contributions are intentionally scoped to a child container (e.g. connection-scoped containers via `ConnectionContainerModule`).
- URI strings for cross-platform file paths, never raw paths
- Localize user-facing strings with `nls.localize()` or `nls.localizeByDefault()`

**Testing:**
- Unit tests: `*.spec.ts`
- UI tests: `*.ui-spec.ts`
- Slow tests: `*.slow-spec.ts`
- Test resources go in `test-resources/` directory

## Technical Requirements

- Node.js ≥24 (per `package.json` `engines`)
- TypeScript ~6.0.3 with explicit `strict: false` plus selected strictness flags (target ES2023, module CommonJS, module resolution bundler)
- React 19 for UI components, compiled with the automatic JSX runtime (`jsx: react-jsx`, `jsxImportSource: @theia/core/shared/react`), so JSX files only need to import React when they use `React.*` types or APIs. `@theia/core` cannot import its own re-export, so `packages/core/tsconfig.json` intentionally overrides `jsxImportSource` with `react` (the same module) — don't "align" it with the base config
- Monaco Editor for code editing

**Key Technologies:**
- Express.js for backend HTTP server
- InversifyJS for dependency injection
- Lerna for monorepo management
- esbuild for application bundling (webpack support was removed in 1.75.0)
- Lumino 2.x for widget system (tabs, panels, dock layout)

**Key Config Files:**
- `configs/base.tsconfig.json` - TypeScript base config (all packages extend this)
- `configs/base.eslintrc.json` - ESLint parser/base rules
- `configs/build.eslintrc.json` - ESLint build rules (packages extend this)
- `configs/mocharc.yml` - Mocha test runner config
- `configs/nyc.json` - Test coverage config

## Commits, Issues, and Pull Requests

- Use Conventional Commits subjects, matching existing history: `type(scope): summary` (e.g. `fix(plugin-ext): ...`, `feat(ai-registry): ...`, `chore(deps): ...`).
- Use the templates in `.github/` when opening issues or PRs.
- **Changelog:** only breaking changes require a manual `CHANGELOG.md` entry; whether a PR is breaking is declared in the `Breaking changes` section of its description. Non-breaking changes do not need an entry, they are collected at release time, so do not add one and never report a missing one as a review finding. Per-PR entries cause frequent conflicts in `CHANGELOG.md` across many PRs.
- Keep commit messages, PR descriptions, issues, and comments **brief and concise** — no padding, marketing language, or restating the diff.
- **Security:** never disclose vulnerabilities via a GitHub issue or PR — report them per `SECURITY.md`. Such issues are deleted on sight.