VSCode Workspaces

vscode-workspaces.md

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

1. Open VSCode
2. Go to File → Add Folder to Workspace...
3. Select your frontend folder
4. Repeat: File → Add Folder to Workspace...
5. Select your backend folder
6. (Optional) Add monorepo root: File → Add Folder to Workspace... and select the parent my-fullstack-app folder
7. Save the workspace: File → Save Workspace As...
8. 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

File Navigation

• 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:

1. Open terminal (Ctrl + `)
2. Click the + dropdown next to the terminal tabs
3. Select the folder where you want the terminal to open
4. 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

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

Making Changes Across Projects

1. Modify your FastAPI endpoints in the backend folder
2. Switch to frontend folder to update API calls
3. Update documentation in the monorepo root if needed
4. 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.