Contribution Points and Manifests

Purpose and Scope

This page explains how VS Code extensions describe themselves to the workbench through extension manifests and contribution points. An extension manifest is the package.json file at the root of an extension. Contribution points are JSON declarations inside the manifest's contributes object that let an extension add languages, commands, themes, validations, debuggers, views, menus, snippets, authentication providers, chat agents, language model tools, and many other features without hard-coding those features into the workbench. The repository uses the same model for bundled extensions, so reading these manifests is one of the fastest ways to understand how core VS Code features are assembled from extension-shaped components.

Sources: src/vs/platform/extensions/common/extensions.ts, extensions/configuration-editing/package.json, extensions/theme-seti/package.json

The model is deliberately declarative. A manifest can say that a language exists, that a JSON file pattern should use a schema, that an icon theme should be offered in the product, or that an extension has desktop and browser entry points. Runtime code still matters, but the manifest is the contract that lets VS Code discover features before loading the extension host. This separation is important for startup performance, web support, remote workspaces, extension management, and feature presentation in the UI. It also lets built-in extensions, Marketplace extensions, and private development extensions share a recognizable packaging shape.

Sources: src/vs/platform/extensions/common/extensions.ts, extensions/configuration-editing/package.json

Relevant Source Files

• src/vs/platform/extensions/common/extensions.ts — Defines platform-facing extension metadata and contribution interfaces such as commands, debuggers, grammars, JSON validation, keybindings, languages, menus, snippets, themes, view containers, views, colors, authentication, walkthroughs, start entries, notebooks, and related contribution shapes.
• extensions/git/package.json — Bundled Git extension manifest used to declare source-control features, activation, dependencies, and user-visible integration points for Git workflows.
• extensions/typescript-language-features/package.json — Bundled TypeScript and JavaScript language feature manifest used to declare language support, activation, configuration, grammars, and language-service-oriented capabilities.
• extensions/configuration-editing/package.json — Bundled configuration editing manifest that declares JSON and JSONC language coverage, schema validation for VS Code configuration files, activation events, desktop and browser entry points, capabilities, dependencies, and an enabled API proposal.
• extensions/theme-seti/package.json — Bundled Seti icon theme manifest that declares a theme category and an iconThemes contribution pointing at the icon theme definition.

Manifest Anatomy

The public manifest fields establish identity, compatibility, packaging, and runtime entry points. In the bundled examples, name, displayName, description, version, publisher, license, and engines appear alongside extension-specific fields such as main, browser, activationEvents, capabilities, dependencies, scripts, and contributes. Marketplace extensions generally use a concrete compatibility range in engines.vscode; a bundled private extension can have repository-specific constraints, as shown by the Seti theme manifest, whose engines.vscode is * because it is shipped as part of the product rather than published as an independent Marketplace package.

Sources: extensions/configuration-editing/package.json, extensions/theme-seti/package.json

Entry points tell VS Code where executable extension code lives when the extension is activated. The configuration editing extension declares a desktop main module and a web browser bundle, which makes the same feature area available in both native and browser-based VS Code environments. Its scripts show the corresponding build paths: regular compilation through a gulp extension task and web bundling through an esbuild script plus a browser TypeScript project. That pattern matters for extension authors because a manifest is not only metadata for discovery; it also connects product capabilities to the build outputs that the extension host can load.

Sources: extensions/configuration-editing/package.json

Activation events are the bridge between declarative discovery and runtime execution. The configuration editing extension activates on profile-related events and when JSON or JSONC language files are used. That is a concrete example of lazy loading: the workbench can recognize contributed languages and schema associations up front, then start the extension only when a relevant profile or language scenario requires code. Contributions that do not need runtime code, such as Seti's icon theme declaration, can be useful even when the manifest has no main or browser entry point. The manifest therefore supports both code-heavy and asset-oriented extensions.

Sources: extensions/configuration-editing/package.json, extensions/theme-seti/package.json

Contribution Points in the Platform Model

The platform file src/vs/platform/extensions/common/extensions.ts captures the internal TypeScript shapes behind many manifest contributions. Interfaces such as ICommand, IDebugger, IGrammar, IJSONValidation, IKeyBinding, ILanguage, IMenu, ISnippet, ITheme, IViewContainer, IView, IColor, and IAuthenticationContribution mirror the kinds of JSON objects that extension manifests provide. These interfaces are not a user tutorial by themselves, but they are valuable for contributors because they reveal the normalized objects that VS Code expects after reading manifests from built-in, user, and development extensions.

Sources: src/vs/platform/extensions/common/extensions.ts

The important design point is that each contribution shape is small and domain-specific. A command has a command identifier and title, with an optional category. A keybinding ties a command to keys and platform-specific overrides. A language has an id, extensions, and aliases. JSON validation maps file matches to schema URLs. Views and view containers supply identifiers and names that the workbench can place into the UI. Authentication contributions provide provider identifiers and labels. By keeping these records concise, VS Code can index available functionality, render feature lists, and route activation events before any extension-specific implementation has run.

Sources: src/vs/platform/extensions/common/extensions.ts

Bundled Manifest Examples

The configuration editing extension is a dense example of a feature extension that primarily teaches VS Code how to understand VS Code-owned configuration files. It contributes jsonc for files such as settings.json, launch.json, tasks.json, mcp.json, keybindings.json, extensions.json, argv.json, profiles.json, and dev container JSON files. It also contributes json support for .code-profile files. These declarations are not merely syntax hints; they make configuration files participate in language mode selection, schema validation, and editor assistance that feels built into the product.

Sources: extensions/configuration-editing/package.json

The same manifest uses jsonValidation entries to bind specific locations and glob patterns to VS Code schema URLs. Examples include default keybindings, user keybindings, profile keybindings, default settings, user settings, profile settings, machine settings, workspace configuration, .code-workspace files, argv.json, folder settings, launch configuration, tasks, MCP configuration, and chat language model configuration. This illustrates a common contribution pattern: the extension declares many narrow file-to-schema associations so the editor can provide precise validation and completion without a monolithic hard-coded switch for every configuration file type.

Sources: extensions/configuration-editing/package.json

The Seti theme extension demonstrates the opposite end of the spectrum. Its manifest is compact, private, categorized as a theme, and focused on a single iconThemes contribution. The contribution gives the icon theme an id, a localized label, and a path to the JSON icon theme definition. That is enough for VS Code to list the theme in icon theme selection UI and load its file icon rules. The example is useful because it shows that an extension can be valuable as a packaged contribution of assets and metadata, not only as a TypeScript module with activation code.

Sources: extensions/theme-seti/package.json

The Git and TypeScript language feature manifests represent larger bundled extensions that use the same contract for source control and language intelligence. Their presence in extensions/git/package.json and extensions/typescript-language-features/package.json is significant because these capabilities feel native to many users, yet they are still declared through extension manifests. This architecture gives VS Code a consistent way to ship first-party features, expose them to extension management, and let other extensions learn from real manifests that exercise commands, activation, configuration, language declarations, and dependency relationships.

Sources: extensions/git/package.json, extensions/typescript-language-features/package.json

Compact Reference

Area	Concrete manifest or platform names	What to look for
Identity	name, displayName, description, version, publisher, license	How the extension is named, localized, versioned, and attributed.
Compatibility	engines.vscode	Which VS Code versions can load the extension; bundled private extensions may differ from Marketplace guidance.
Runtime	main, browser, activationEvents	When the extension activates and which desktop or web entry point is loaded.
Workspace behavior	capabilities.virtualWorkspaces, capabilities.untrustedWorkspaces	Whether the extension is allowed in virtual or untrusted workspace contexts.
API access	enabledApiProposals	Proposed APIs an extension opts into, such as profileContentHandlers in configuration editing.
Contributions	contributes.languages, contributes.jsonValidation, contributes.iconThemes	Declarative features that VS Code can discover without running extension code.
Platform shapes	ICommand, ILanguage, IJSONValidation, IKeyBinding, IView, IAuthenticationContribution	Internal TypeScript contracts that correspond to common contribution point objects.

Authoring and Review Flow

When reviewing or authoring a manifest, start with the user's visible capability rather than the implementation file. If the feature adds editor behavior for a file type, look for a language contribution, grammar, schema, command, or activation event. If it adds UI, inspect commands, menus, views, view containers, walkthroughs, themes, or icon themes. If it runs code, confirm the main and browser entry points match the supported environments. If it touches workspaces, verify the capability declarations for virtual and untrusted workspaces. This approach keeps the manifest review aligned with what VS Code can discover and present to users.

Sources: src/vs/platform/extensions/common/extensions.ts, extensions/configuration-editing/package.json, extensions/theme-seti/package.json

For repository contributors, the practical next step is to compare a small manifest with a large one. extensions/theme-seti/package.json shows the minimum shape for a packaged visual contribution, while extensions/configuration-editing/package.json shows how activation, schemas, language declarations, dependencies, capabilities, and build scripts combine in a feature extension. From there, inspect the Git and TypeScript language feature manifests to see how complex built-in functionality remains grounded in the same extension model. Related pages to read next are Extension Authoring Overview, Built-in Language Extensions, Themes and Product Icons, Settings and Keybindings, and Git Extension API.