Launch Configurations

Purpose and Scope

A launch configuration is the saved description of how VS Code should start or attach a debugger for a project. The user-facing file is usually .vscode/launch.json, and the official workflow is to create that file when a simple F5 run is not enough. Typical reasons include choosing an application entry point, selecting an attach target, setting environment variables, composing multiple debug targets, or preserving team-specific debugging defaults in the workspace. This page explains the launch configuration concept and connects it to the editor support that makes these JSON-like files practical to author.

Launch configuration authoring sits at the intersection of debugging, JSON editing, language configuration, and task orchestration. The debug extension or debug adapter owns the meaning of fields such as type, request, program, and adapter-specific options. The editor platform supplies the everyday ergonomics: bracket awareness, language-scoped tokenization, replacement commands, and syntax rendering used by panels and generated explanations. Those support systems matter because configuration files are edited as code, reviewed with the project, and often include nested objects, variable expressions, and command strings.

Sources: src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts, src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts, extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/index.ts

Relevant Source Files

• src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts implements BasicInplaceReplace, a generic editor language support that cycles numeric values and common keyword sets. It is relevant to configuration editing because launch and task files are edited through the same editor primitives used across language modes.
• src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts implements LanguageBracketsConfiguration, which turns a language configuration into opening and closing bracket metadata plus a bracket regular expression. It supports structured editing for JSON-like configuration files with nested objects and arrays.
• extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/index.ts exports the bundled grammars used by Copilot shared panels, including JavaScript React, Markdown with LaTeX, Markdown math, search results, and related languages.
• extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/javaScriptReact.tmLanguage.ts provides syntax grammar data for JavaScript React snippets rendered in Copilot panels, which can appear when Copilot explains or generates debug setup code.
• extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/markdown-latex-combined.tmLanguage.ts provides a combined Markdown and LaTeX grammar used in rendered Copilot content, including explanatory debug guidance.
• extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/md-math.tmLanguage.ts defines the markdown-math LanguageInput used for math-oriented Markdown tokenization in shared panels.

Launch Configuration Model

The core shape of a launch file is a JSON object with a version and a configurations array. Each configuration has a type that selects a debug adapter, a request that is usually launch or attach, and a name that appears in the Run and Debug UI. A Node.js example often includes skipFiles and a program value such as ${workspaceFolder}/app.js. C/C++ launch configurations require the program path so the debugger knows which executable and symbols to load, while attach configurations use similar information for a running process.

Compound launch configurations extend that model by starting more than one named configuration at the same time. This is useful when a web application requires a server process, browser target, and worker process to be debugged together. In practice, launch configuration authors should keep adapter-specific settings close to the configuration that needs them and use workspace variables where paths differ across machines. The same variable form also appears in related VS Code configuration files, including MCP configuration, where ${workspaceFolder} is used to refer to the open project.

A representative minimal configuration looks like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/app.js"
    }
  ]
}

Editing Support and Language Behavior

Launch files are configuration documents, but they rely on the same editor-language infrastructure as source files. LanguageBracketsConfiguration receives a languageId and a LanguageConfiguration, filters configured bracket pairs, builds cached opening and closing bracket kinds, and exposes helpers such as getOpeningBracketInfo, getClosingBracketInfo, getBracketInfo, and getBracketRegExp. For a nested JSON-style document, this supports consistent bracket recognition for arrays, objects, and language-specific bracket pairs used by the editor.

The bracket implementation also distinguishes bracket pairs used for colorization. If no explicit colorizedBracketPairs are configured, it starts from ordinary bracket pairs but excludes < and > by default because many languages use those characters as comparison operators. That detail illustrates a broader constraint in VS Code configuration editing: editor services must be general enough for many languages, while avoiding visual or structural assumptions that would be misleading in some syntaxes. Launch configurations benefit from this infrastructure when the user is navigating nested objects or repairing mismatched delimiters.

Sources: src/vs/editor/common/languages/supports/languageBracketsConfiguration.ts

BasicInplaceReplace is another small but useful editor primitive. Its navigateValueSet method checks one or two candidate ranges and returns a replacement range plus value when it can produce a next or previous value. It first tries numeric replacement, preserving decimal precision by scaling the number before incrementing or decrementing, and then falls back to text replacement. The built-in text sets include booleans and visibility modifiers such as public, protected, and private. In configuration authoring, this kind of operation reflects VS Code’s approach to small, language-independent editing commands.

Sources: src/vs/editor/common/languages/supports/inplaceReplaceSupport.ts

Variables, Tasks, and Debug Flow

Variable substitution is the bridge between reusable launch files and machine-specific workspaces. The most common variable is ${workspaceFolder}, which lets a configuration point at the current project without hard-coding an absolute path. Other debug adapters may support inputs, commands, environment variables, symbol search paths, or additional library search paths. The important design rule is that the launch file records intent, while the active workspace, selected folder, and debug adapter resolve the concrete runtime values at launch time.

Tasks commonly enter the flow through pre-launch or post-debug behavior: build before debugging, start a development server, generate assets, or clean up after a session. The debug configuration does not replace a task runner; it refers to task definitions when the project needs repeatable preparation. This separation lets teams evolve build automation without rewriting every adapter-specific setting. When authoring configurations, prefer a small launch entry that names the executable or entry point and delegates repeatable shell work to tasks.

Copilot can help generate or explain launch configurations, and the repository includes shared panel grammars that render language-aware content in Copilot surfaces. The language index re-exports javascriptreact, markdownLatexCombined, markdownMath, and other grammars, while the Markdown math grammar defines token names for comments, functions, constants, braces, round brackets, numbers, and operators. These files do not define debugger behavior; they support readable, syntax-aware AI panel content that may include configuration snippets, explanations, and generated code blocks.

Sources: extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/index.ts, extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/md-math.tmLanguage.ts, extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/javaScriptReact.tmLanguage.ts, extensions/copilot/src/extension/completions-core/vscode-node/extension/src/panelShared/languages/markdown-latex-combined.tmLanguage.ts

Compact Reference

Implementation Notes and Next Steps

When troubleshooting a launch configuration, separate syntax problems from debugger problems. Syntax and editing issues appear while editing the JSON-like document: mismatched braces, malformed arrays, invalid strings, or confusing generated snippets. Runtime debugger issues appear after the configuration is selected: missing executables, wrong symbols, environment differences, or attach targets that are not running. This split helps decide whether to inspect editor feedback, adapter documentation, task output, or the Debug Console.

For the next step, create the smallest working launch entry for the runtime you use, verify that it starts with F5, and only then add environment variables, task hooks, or compound entries. If Copilot generates a configuration, review the selected type, request, and path variables before committing it. Related pages in this wiki cover the broader debugging workflow, task runners, JavaScript and TypeScript support, and Copilot-assisted editing surfaces.