Treat Editor Setup as Code: VS Code Workspace Recommendations and Settings for Reproducible Repos

A new contributor clones your repository, opens the folder in Visual Studio Code, and immediately faces a silent guessing game. Which formatter does the team expect? Is there a linter? Should the editor insert final newlines? If the answer lives in a Slack thread or a senior engineer's head, the repo is missing a piece of its own documentation. The useful takeaway is straightforward: commit a small .vscode/extensions.json recommendation list and matching .vscode/settings.json so the repository itself advertises the editor tooling it expects.

What the repository can advertise

VS Code supports workspace extension recommendations through .vscode/extensions.json. The file contains two arrays of extension IDs: recommendations and unwantedRecommendations. When a developer opens the folder, VS Code surfaces the recommended list in the Extensions view and can prompt about them. Unwanted entries suppress noisy suggestions from other extensions. This is advisory, not a provisioning system: VS Code will not silently install anything.

Settings that follow the folder

Workspace settings live in .vscode/settings.json and override user settings for that folder. Use them for narrow, project-specific choices: the default formatter, format-on-save behavior, line endings, and language-specific blocks. Personal preferences—theme, keybindings, font size—belong in user settings so the repo file stays reviewable and small. Because workspace settings can influence tasks and debugging, be cautious with repos you clone; VS Code's Workspace Trust feature may restrict some folder-level settings until you explicitly trust the workspace.

A TypeScript API example

Consider a TypeScript API repository that expects ESLint for linting and Prettier for formatting. At the repository root, create .vscode/extensions.json:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ],
  "unwantedRecommendations": [
    "publisher.conflicting-formatter"
  ]
}

Then create .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

The [typescript] block is optional but shows how to scope a formatter to a language. Extension IDs must be exact publisher.name values; a typo silently produces a recommendation that cannot be installed.

Limitations and practical checks

Recommendations do not enforce anything. A contributor can ignore the list, and the extensions still need the underlying toolchain—Node, an ESLint configuration, a Prettier configuration—to do useful work. The .vscode folder is easy to clutter; review it like code and avoid committing machine-specific paths. Settings names and UI labels can change across VS Code releases, so verify against the version your team standardizes on.

To check the result, open the Extensions view (Ctrl+Shift+X or Cmd+Shift+X) and look for the workspace recommendations section; confirm your IDs appear. To prove the file is the source, rename .vscode/extensions.json to .vscode/extensions.json.bak and reload the window—the recommendations section should disappear. Use the command palette to run Preferences: Open Workspace Settings (JSON) and confirm the settings are stored under .vscode/settings.json. Finally, run the formatter on a sample file and compare the result with your CI or pre-commit output so the editor and pipeline agree.

Make it part of the repo

Add both files to the repository, list only extensions that change correctness or formatting, document expected runtime versions in the README, and add a CI check or pre-commit hook for formatting. That way the editor setup is reproducible, reviewable, and visible to everyone who clones the project.