Repository: eclipse-theia/theia

Stars: 21470

CLAUDE.md Copy Chapter

CLAUDE.md

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

Development Commands Copy Chapter

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 Copy Chapter

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:

"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 Copy Chapter

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 Copy Chapter

- 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 Copy Chapter

<br/>
<div id="theia-logo" align="center">
<br />
<img src="https://raw.githubusercontent.com/eclipse-theia/theia/master/logo/theia-logo-gray.svg?sanitize=true" alt="Theia Logo" width="300"/>
<h3>Cloud & Desktop IDE Framework</h3>
</div>

<div id="badges" align="center">


Eclipse Theia is an extensible framework to develop full-fledged multi-language Cloud & Desktop IDEs and tools with state-of-the-art web technologies.

</div>

- Website
- Repositories
- Releases
- Scope
- Roadmap
- Getting Started
- Contributing
- Feedback
- Documentation
- License
- Trademark

<div style='margin:0 auto;width:60%;'>

!Theia

</div>

Website Copy Chapter

Visit the Eclipse Theia website for more information and the Theia documentation.

Repositories Copy Chapter

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 and the Theia website. Please also see the overview of all Theia project repositories.

Releases Copy Chapter

- All available releases are available on GitHub including changelogs.
- Detailed release announcements are linked on the Theia website.
- Community Releases are listed on the Theia website.
- Visit the release website for more information.

Scope Copy Chapter

- 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 are available on the Theia website.

Roadmap Copy Chapter

See our roadmap for an overview about the current project goals and the upcoming releases.

Getting Started Copy Chapter

Here you can find guides and examples for common scenarios to adopt Theia:

- Get an overview of how to get started on the Theia website
- Develop a Theia application - your own IDE/Tool
- Learn about Theia's extension mechanisms
- Develop a VS Code like extension
- Develop a Theia extension
- Test a VS Code extension in Theia
- Package a desktop Theia application with Electron

Contributing Copy Chapter

Read below to learn how to take part in improving Theia:

- Fork the repository and run the examples from source
- Get familiar with the development workflow, Coding Guidelines, Code of Conduct and sign the 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 to get you familiar with GitHub contributing process.
- First time contributing to Theia? Pick a beginner friendly issue 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 is a good list to start. Further, have a look at our roadmap to align your contributions with the current project goals.
- Could not find an issue? Look for bugs, typos, and missing features.

Feedback Copy Chapter

Read below how to engage with Theia community:

- Join the discussion on GitHub.
- Ask a question, request a new feature and file a bug with GitHub issues.
- 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.
- Join the weekly developer call

Documentation Copy Chapter

- API Documentation
- General Documentation
- VS Code API Compatibility Report
- Useful Links:
- Developing
- Testing
- Migration Guide
- API Integration Testing
- Coding Guidelines
- Code Organization
- Plugin and VSCode API

SBOM Copy Chapter

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.

License Copy Chapter

- Eclipse Public License 2.0
- 一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception

Trademark Copy Chapter

"Theia" is a trademark of the Eclipse Foundation. Learn More