VSCode Workspace Guide for Full-Stack Development

What are VSCode Workspaces?

A VSCode workspace is a collection of one or more folders that are opened together in a single VSCode window. Think of it as a container that holds multiple related projects, allowing you to work on them simultaneously.

Why VSCode Needs to Know Project Root Folders

VSCode relies on knowing the root folder of each project to function properly. Here’s why this matters:

Language Support and IntelliSense

VSCode looks for configuration files like package.json, requirements.txt, or pyproject.toml in the root folder
These files tell VSCode what language tools and dependencies are available
Without knowing the root, features like auto-completion and error detection won’t work properly

File Path Resolution

Import statements and file references are resolved relative to the project root
VSCode needs to understand the project structure to provide accurate suggestions and navigation

Tool Integration

Development tools (linters, formatters, debuggers) expect to run from the project root
Package managers like npm or pip need to find their configuration files
Build tools and scripts are typically configured to run from the root directory

Example Problem Without Proper Root Setup: If you open your entire my-fullstack-app folder as a single project, VSCode might get confused:

It won’t find package.json when working in React files (because it’s in a subfolder)
Python imports might not resolve correctly
npm commands won’t work because VSCode doesn’t know where the frontend project starts

By setting up a workspace with proper root folders, you tell VSCode: “This frontend folder is a complete React project” and “This backend folder is a complete Python project.”

Why Use Workspaces for Full-Stack Development?

When working on full-stack applications in a monorepo, you have separate codebases for your frontend and backend in the same repository. Using workspaces provides several key benefits:

Unified Development Environment

Keep related projects together in one window
Switch between frontend and backend code instantly
Maintain context without losing your place

Enhanced Productivity

Search across both codebases simultaneously
Use integrated terminal for both projects
View file changes side-by-side
Access monorepo root files alongside individual projects

Setting Up a Workspace: React + FastAPI Monorepo Example

Let’s walk through creating a workspace for a full-stack project with a React Vite frontend and Python FastAPI backend in a single repository.

Step 1: Organize Your Monorepo Structure

Your monorepo should be organized with clear separation between projects:

my-fullstack-app/
├── .git/              # Single Git repository
├── README.md          # Project documentation
├── .gitignore         # Shared gitignore
├── frontend/          # React Vite project
│   ├── src/
│   ├── public/
│   ├── package.json
│   └── vite.config.js
└── backend/           # FastAPI project
    ├── main.py
    ├── requirements.txt
    └── app/

Step 2: Create the Workspace

Method 1: Using the File Menu

Open VSCode
Go to File → Add Folder to Workspace...
Select your frontend folder
Repeat: File → Add Folder to Workspace...
Select your backend folder
(Optional) Add monorepo root: File → Add Folder to Workspace... and select the parent my-fullstack-app folder
Save the workspace: File → Save Workspace As...
Save it in your monorepo root as project.code-workspace

Method 2: Create Workspace File Manually Create a file called project.code-workspace in your monorepo root with this content:

{
    "folders": [
        {
            "name": "Monorepo Root",
            "path": "."
        },
        {
            "name": "Frontend (React)",
            "path": "./frontend"
        },
        {
            "name": "Backend (FastAPI)",
            "path": "./backend"
        }
    ]
}

Including the monorepo root gives you easy access to:

README.md and project documentation
.gitignore and other configuration files
Package scripts that might operate on the entire project
Any shared configuration or utilities

Working with Your Monorepo Workspace

Use the Explorer panel to navigate between all three folders
The “Monorepo Root” section shows your top-level files
Use Ctrl+P (or Cmd+P on Mac) to quickly open files from any part of your project

Important: When working on frontend or backend code, always open files from their respective workspace folders (Frontend or Backend), not from the Monorepo Root. This ensures VSCode uses the correct project context for language support, IntelliSense, and tool integration. The Monorepo Root folder should primarily be used for accessing top-level files like README.md, .gitignore, or project configuration files.

Integrated Terminal Management

Open separate terminals for each project:

Open terminal (Ctrl + `)
Click the + dropdown next to the terminal tabs
Select the folder where you want the terminal to open
Run your development servers:
- Frontend terminal: npm run dev
- Backend terminal: fastapi dev main.py

Git Management

Since everything is in one repository:

All changes from frontend, backend, and root files appear in a single Source Control panel
You can commit changes from all projects together
Branching affects the entire monorepo
This keeps everything synchronized and simplifies deployment

Common Workflows

Starting Development

Open your project.code-workspace file in VSCode
Open integrated terminal for backend folder
Activate virtual environment: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows)
Start FastAPI server: fastapi dev main.py
Open new terminal for frontend folder
Start React development server: npm run dev

Making Changes Across Projects

Modify your FastAPI endpoints in the backend folder
Switch to frontend folder to update API calls
Update documentation in the monorepo root if needed
All changes appear in one Git panel for easy committing

Managing Documentation and Configuration

Edit README.md from the Monorepo Root folder
Update .gitignore to exclude files from both projects
Add project-wide scripts or configuration files at the root level

Best Practices

Workspace File Location

Store your .code-workspace file in the monorepo root
This makes it easy for team members to open the complete setup
Include the workspace file in your Git repository so everyone uses the same setup

Folder Organization

Keep frontend and backend completely separate
Use clear, descriptive names for your workspace folders
Include the monorepo root for easy access to project-wide files

Terminal Management

Use separate terminals for frontend and backend development servers
Keep a third terminal open at the monorepo root for Git operations
This allows you to run multiple processes without conflicts

Opening Your Workspace

Once you’ve created your workspace file, you can:

Double-click the .code-workspace file to open it
Use File → Open Workspace from File... in VSCode
Recent workspaces will appear in File → Open Recent
Team members can clone the repo and immediately open the workspace file

Why Monorepos Work Well for Full-Stack Projects

Using a monorepo structure with VSCode workspaces is particularly beneficial for full-stack development because:

Simplified Git workflow: One repository to clone, one place for all commits
Easy deployment: Both frontend and backend can be deployed together
Shared documentation: README files and project notes stay with the code
Team collaboration: Everyone works with the same workspace setup
Learning focus: Developers can focus on coding rather than managing multiple repositories

Using VSCode workspaces with a monorepo structure streamlines your full-stack development workflow while keeping everything organized and easily accessible. This setup is ideal for developers working with multiple technologies in a single, cohesive project.