VS Code Multi-Root Workspaces: A Guide to Monorepo Productivity

When I first started managing a codebase that spanned three distinct microservices and a shared library, I spent half my day switching between different VS Code windows. It was a mess. I’d lose my place, my terminal sessions would overlap, and I was constantly misconfiguring project-specific extensions. Switching to VS Code multi-root workspaces changed that workflow entirely, allowing me to treat a massive repository as a single, cohesive unit.

If you’ve ever felt like your IDE is fighting you while working on a monorepo, you’re likely missing out on the power of the .code-workspace file. This feature isn't just about grouping folders; it's about context-aware development.

Why Multi-Root Workspaces Matter

A standard VS Code setup works fine for a single folder, but it falls apart when you have disparate projects in one root. By using multi-root workspaces, you define a single configuration that tells VS Code exactly which folders belong together.

I’ve found that this is the best way to handle monorepo development because it lets you:

• Configure project-specific settings that don't leak into other folders.
• Run tasks across multiple roots simultaneously.
• Maintain a clean, unified view of your file tree without cluttering the workspace with irrelevant node_modules folders.

Before I landed on this approach, I tried using symlinks to trick VS Code into seeing my shared libraries. It worked for about two days until a git clean command wiped out my symlinks and broke my local environment. I learned the hard way that native workspace features are always more stable than clever workarounds.

Setting Up Your Workspace

To get started, you don't need a plugin. Just go to File > Add Folder to Workspace... and select the directories you need. Once you’ve added them, save the configuration by going to File > Save Workspace As.... This creates a .code-workspace file, which is just a JSON file that looks like this:

JSON
{
	"folders": [
		{ "path": "services/api" },
		{ "path": "services/frontend" },
		{ "path": "libs/shared-types" }
	],
	"settings": {
		"editor.formatOnSave": true
	}
}

This file is the secret sauce for VS Code productivity. Because it's a file, you can commit it to your repository. This ensures that every developer on your team has the same IDE setup, which saves hours of "it works on my machine" debugging. If you’re interested in how this type of consistency impacts your velocity, I’ve written previously about why developer productivity: why I stopped writing clean code first to keep the momentum going.

Managing Project-Specific Configurations

The real power of VS Code configuration in a multi-root setup is the ability to nest settings. You can define global settings for the entire workspace, or override them for specific folders.

For example, if my services/api folder needs a different version of a linter than my services/frontend folder, I can define that inside the settings object of the .code-workspace file:

I usually keep the workspace file as the source of truth for the project. It prevents the need to constantly tweak global IDE settings when switching between a React project and a PHP backend. In fact, when I'm dealing with complex structures, I often apply lessons from React component architecture: mastering colocation for better maintainability to ensure that my workspace organization mirrors the actual physical structure of the components.

Common Pitfalls

Don't get too aggressive with your folder inclusion. If you include your entire root directory plus sub-directories, VS Code will index everything twice. This leads to high CPU usage and slow search results—I once saw my memory usage jump by roughly 1.2GB just by adding a redundant root.

Also, be careful with extensions. Some extensions don't handle multi-root setups well. If you find a specific tool acting up, check its documentation to see if it supports multi-root workspaces. Usually, a quick restart of the extension host (run Developer: Reload Window from the command palette) fixes about 90% of these weird glitches.

FAQ

Q: Can I have multiple workspace files for the same project? A: Absolutely. I often keep a frontend.code-workspace and a backend.code-workspace in the same repo if I want to keep my focus narrow during specific tasks.

Q: Does adding a folder to a workspace affect my git status? A: No. The workspace file is just a set of instructions for VS Code. It doesn't change how Git tracks your files.

Q: Will this slow down my IDE? A: If you add too many large folders (especially those with massive node_modules), yes. Be selective about what you add to the workspace.

Final Thoughts

I’m still experimenting with how to best share these workspace files across a distributed team without them becoming stale. Sometimes a developer adds a new service and forgets to update the shared .code-workspace file. It's a small friction point, but it's worth it for the organization you gain. Start small, add the folders you actually touch daily, and let the IDE do the heavy lifting for you.