This guide covers the essential information for developers who want to contribute to code-server. Unlike typical Node.js projects, code-server development involves working with the VS Code codebase through a patch-based integration system, a multi-stage build pipeline, and comprehensive testing infrastructure.
This page provides an overview of the development environment and key systems. For step-by-step setup instructions, see Development Setup. For daily development workflows, see Development Workflow. For contribution requirements and guidelines, see Contributing Guidelines.
code-server development requires understanding three major systems that interact during the development cycle:
Sources: docs/CONTRIBUTING.md28-54 .tours/contributing.tour6-149
code-server integrates VS Code as a submodule located at lib/vscode and applies modifications using quilt-managed patches stored in patches/. This approach allows tracking upstream VS Code releases while maintaining code-server-specific features.
The patch system enables:
/proxy/ and /absproxy/ routes src/node/routes/pathProxy.ts78SettingsProvider src/node/settings.ts26-29Patches are applied sequentially according to patches/series. When updating the VS Code version, developers must pop all patches, update the submodule, and re-apply them, resolving conflicts manually if needed docs/CONTRIBUTING.md94-107
Sources: docs/CONTRIBUTING.md48-49 docs/CONTRIBUTING.md94-107 docs/CONTRIBUTING.md108-121 src/node/settings.ts26-29 src/node/routes/pathProxy.ts78
The build process consists of multiple stages orchestrated through npm scripts defined in package.json. A full production release requires building both the code-server wrapper and the patched VS Code submodule.
| Stage | Command | Purpose |
|---|---|---|
| VS Code Build | npm run build:vscode | Compile VS Code with patches applied docs/CONTRIBUTING.md134 |
| code-server Build | npm run build | Compile code-server TypeScript source docs/CONTRIBUTING.md133 |
| Release Bundle | npm run release | Create a bundled package in ./release docs/CONTRIBUTING.md135 |
| Package Creation | npm run package | Create .deb, .rpm, and .tar.gz artifacts docs/CONTRIBUTING.md161 |
Sources: docs/CONTRIBUTING.md122-165
code-server employs a multi-layered testing strategy docs/MAINTAINING.md79-94:
Unit Tests:
src/node/.npm run test:unit docs/MAINTAINING.md86-87Script Tests:
bats.test/scripts docs/MAINTAINING.md88-89End-to-End Tests:
test/e2e docs/MAINTAINING.md90-91Sources: docs/CONTRIBUTING.md16-20 docs/CONTRIBUTING.md52-53 docs/MAINTAINING.md79-94
The code-server repository is organized into several key areas:
| File | Purpose |
|---|---|
| src/node/entry.ts66 | Main entry point; parses CLI and starts the HTTP server. |
| src/node/cli.ts28-35 | Describes all code-server CLI options and parsing logic. |
| src/node/app.ts11-15 | Core HTTP and Web Socket server creation. |
| src/node/routes/vscode.ts116-119 | Serves VS Code HTML and handles workbench websockets. |
| src/node/vscode.ts121-124 | Handles the actual spawning of the VS Code child process. |
| src/node/settings.ts26-29 | Manages reading and writing the code-server settings file. |
Sources: .tours/contributing.tour11-125
The typical development cycle follows these stages:
Modifying code-server Source:
src/node/ (Node.js) or src/browser/ (Frontend) .tours/contributing.tour6-8npm run watch to launch a live-reloading instance on localhost:8080 docs/CONTRIBUTING.md73-75Modifying VS Code Patches:
quilt push and quilt pop to navigate the patch stack docs/CONTRIBUTING.md113quilt add before modifying a file in lib/vscode docs/CONTRIBUTING.md115quilt refresh to save changes into the .diff file docs/CONTRIBUTING.md120Sources: docs/CONTRIBUTING.md67-79 docs/CONTRIBUTING.md108-123 .tours/contributing.tour6-8
Development requirements vary by operating system due to native module compilation:
Requires build-essential, libx11-dev, libxkbfile-dev, and libsecret-1-dev for VS Code compatibility docs/CONTRIBUTING.md55-62
Requires Xcode command line tools and specific environment setups for native modules.
Requires C++ compiler toolchain and specific handling for path lengths and native modules.
Android is not natively seen as a Linux environment. Developers often use a JS override to pretend the platform is linux to allow extension installation.
Sources: docs/CONTRIBUTING.md55-62
Refresh this wiki