# Repository: eclipse-theia/theia
# Stars: 21470
## CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Development Commands
**Essential commands:**
- `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 via webpack β otherwise the running browser app won't include your latest changes.
**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 with 77 packages
- `/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)
- @.prompts/project-info.prompttemplate (practical patterns for contributions, widgets, commands, preferences, plugin API, styling)
**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 β₯20
- TypeScript ~5.9.3 with strict settings (target ES2023, module CommonJS)
- React 18.2.0 for UI components
- Monaco Editor for code editing
**Key Technologies:**
- Express.js for backend HTTP server
- InversifyJS for dependency injection
- Lerna for monorepo management
- Webpack for application bundling
- 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
## README.md
Cloud & Desktop IDE Framework
[](https://github.com/eclipse-theia/theia/labels/help%20wanted)
[](https://github.com/eclipse-theia/theia/actions/workflows/ci-cd.yml?query=branch%3Amaster)
[](https://github.com/eclipse-theia/vscode-builtin-extensions/actions/workflows/build.yml?query=branch%3Amaster)
[](https://github.com/eclipse-theia/theia/discussions/categories/q-a)
[](https://github.com/eclipse-theia/theia/labels/bug)
Eclipse Theia is an extensible framework to develop full-fledged multi-language Cloud & Desktop IDEs and tools with state-of-the-art web technologies.
- [Website](#website)
- [Repositories](#repositories)
- [Releases](#releases)
- [Scope](#scope)
- [Roadmap](#roadmap)
- [Getting Started](#getting-started)
- [Contributing](#contributing)
- [Feedback](#feedback)
- [Documentation](#documentation)
- [License](#license)
- [Trademark](#trademark)
## Website
[Visit the Eclipse Theia website](http://www.theia-ide.org) for more information and [the Theia documentation](http://www.theia-ide.org/docs).
## Repositories
This is the main repository for the Eclipse Theia project, containing the sources of the Theia Platform. Please open generic discussions, bug reports and feature requests about Theia on this repository. The Theia project also includes additional repositories, e.g. for the [artifacts building the Theia IDE](https://github.com/eclipse-theia/theia-blueprint) and the [Theia website](https://github.com/eclipse-theia/theia-website). Please also see the [overview of all Theia project repositories](https://github.com/eclipse-theia).
## Releases
- [All available releases](https://github.com/eclipse-theia/theia/releases) are available on GitHub including changelogs.
- [Detailed release announcements](https://theia-ide.org/resources/) are linked on the Theia website.
- [Community Releases](https://theia-ide.org/releases/) are listed on the Theia website.
- [Visit the release website](https://theia-ide.org/releases/) for more information.
## Scope
- Support building browser-based and desktop IDEs and tools
- Provide a highly flexible architecture for adopters
- Support VS Code Extension protocol
- Develop under vendor-neutral open-source governance
[More details on the project goals](https://theia-ide.org/docs/project_goals/) are available on the Theia website.
## Roadmap
See [our roadmap](https://github.com/eclipse-theia/theia/wiki/Eclipse-Theia-Roadmap) for an overview about the current project goals and the upcoming releases.
## Getting Started
Here you can find guides and examples for common scenarios to adopt Theia:
- [Get an overview of how to get started](https://theia-ide.org/#gettingstarted) on the Theia website
- [Develop a Theia application - your own IDE/Tool](https://theia-ide.org/docs/composing_applications/)
- [Learn about Theia's extension mechanisms](https://theia-ide.org/docs/extensions/)
- [Develop a VS Code like extension](https://theia-ide.org/docs/authoring_vscode_extensions/)
- [Develop a Theia extension](https://theia-ide.org/docs/authoring_extensions/)
- [Test a VS Code extension in Theia](https://github.com/eclipse-theia/theia/wiki/Testing-VS-Code-extensions)
- [Package a desktop Theia application with Electron](https://theia-ide.org/docs/blueprint_documentation/)
## Contributing
Read below to learn how to take part in improving Theia:
- Fork the repository and [run the examples from source](doc/Developing.md#quick-start)
- Get familiar with [the development workflow](doc/Developing.md), [Coding Guidelines](doc/coding-guidelines.md), [Code of Conduct](CODE_OF_CONDUCT.md) and [sign the Eclipse contributor agreement](CONTRIBUTING.md#eclipse-contributor-agreement)
- Find an issue to work on and submit a pull request
- First time contributing to open source? Pick a [good first issue](https://github.com/eclipse-theia/theia/labels/good%20first%20issue) to get you familiar with GitHub contributing process.
- First time contributing to Theia? Pick a [beginner friendly issue](https://github.com/eclipse-theia/theia/labels/beginners) to get you familiar with codebase and our contributing process.
- Want to become a Committer? Solve an issue showing that you understand Theia objectives and architecture. [Here](https://github.com/eclipse-theia/theia/labels/help%20wanted) is a good list to start. Further, have a look at our [roadmap](https://github.com/eclipse-theia/theia/wiki/Eclipse-Theia-Roadmap) to align your contributions with the current project goals.
- Could not find an issue? Look for bugs, typos, and missing features.
## Feedback
Read below how to engage with Theia community:
- Join the discussion on [GitHub](https://github.com/eclipse-theia/theia/discussions).
- Ask a question, request a new feature and file a bug with [GitHub issues](https://github.com/eclipse-theia/theia/issues/new/choose).
- Vote on existing GitHub issues by reacting with a π. We regularly check issues with votes!
- Star the repository to show your support.
- Follow Theia on [X](https://x.com/theia_ide).
- Join the [weekly developer call](https://github.com/eclipse-theia/theia/wiki/Dev-Meetings)
## Documentation
- [API Documentation](https://eclipse-theia.github.io/theia/docs/next/index.html)
- [General Documentation](https://theia-ide.org/docs/)
- [VS Code API Compatibility Report](https://eclipse-theia.github.io/vscode-theia-comparator/status.html)
- Useful Links:
- [Developing](doc/Developing.md)
- [Testing](doc/Testing.md)
- [Migration Guide](doc/Migration.md)
- [API Integration Testing](doc/api-testing.md)
- [Coding Guidelines](doc/coding-guidelines.md)
- [Code Organization](doc/code-organization.md)
- [Plugin and VSCode API](doc/Plugin-API.md)
## SBOM
To enhance supply chain security and offer users clear insight into project components, Eclipse Theia now generates a Software Bill of Materials (SBOM) for every release. These are published to the Eclipse Foundation SBOM registry, with access instructions and usage details available in this [documentation](https://eclipse-csi.github.io/security-handbook/sbom/registry.html).
## License
- [Eclipse Public License 2.0](LICENSE-EPL)
- [δΈ (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception](LICENSE-GPL-2.0-ONLY-CLASSPATH-EXCEPTION)
## Trademark
"Theia" is a **trademark of the Eclipse Foundation**. [Learn More](https://www.eclipse.org/theia)