Mastering Development: Coding Projects on WSL with VS Code

Windows Subsystem for Linux (WSL) combined with Visual Studio Code creates a powerful development environment that brings the best of both Windows and Linux worlds. This guide walks you through setting up, configuring, and optimizing your coding projects on WSL with VS Code.

Why WSL + VS Code?

The combination of WSL and VS Code offers several compelling advantages:

Native Linux environment without dual-booting or virtual machines
Seamless integration between Windows UI and Linux command line
Fast file system performance when working within WSL
Access to Linux tools while maintaining Windows productivity apps
Consistent deployment environment matching production servers

Prerequisites

Before diving in, ensure you have:

Windows 10 version 2004+ or Windows 11
WSL 2 installed and configured
Visual Studio Code installed on Windows
Remote - WSL extension for VS Code

Setting Up Your First Project

Step 1: Install Remote - WSL Extension

Open VS Code and install the Remote - WSL extension:

Press Ctrl+Shift+X to open Extensions
Search for "Remote - WSL"
Click Install on the official Microsoft extension
Restart VS Code if prompted

Step 2: Connect to WSL

Launch your WSL distribution (Ubuntu, Debian, etc.) and navigate to your projects directory:

# Create a projects directory if it doesn't exist
mkdir -p ~/projects
cd ~/projects

Open VS Code from within WSL:

code .

This launches VS Code on Windows but connects to the WSL filesystem. You'll see "WSL: Ubuntu" (or your distro name) in the bottom-left corner.

Step 3: Initialize Your Project

Let's create a Node.js project as an example:

# Create project directory
mkdir my-awesome-app
cd my-awesome-app

# Initialize Node.js project
npm init -y

# Open in VS Code
code .

Project Structure Best Practices

File Organization

Keep your projects organized within the WSL filesystem for optimal performance:

~/projects/
├── web-apps/
│   ├── frontend-react/
│   ├── backend-node/
│   └── fullstack-nextjs/
├── mobile-apps/
│   └── react-native-app/
├── scripts/
│   └── automation/
└── learning/
    └── tutorials/

Important: Store active projects in the Linux filesystem (~/projects), not in /mnt/c/. File I/O is significantly faster in native WSL filesystem.

Setting Up Development Tools in WSL

Install Essential Tools

# Update package lists
sudo apt update

# Install build essentials
sudo apt install -y build-essential curl git

# Install Node.js via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

# Verify installations
node --version
npm --version
git --version

Configure Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global core.editor "code --wait"
git config --global init.defaultBranch main

Set Up SSH Keys for GitHub/GitLab

# Generate SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"

# Start SSH agent
eval "$(ssh-agent -s)"

# Add SSH key
ssh-add ~/.ssh/id_ed25519

# Copy public key
cat ~/.ssh/id_ed25519.pub
# Copy the output and add to GitHub/GitLab SSH keys

VS Code Configuration for WSL

Recommended Extensions

Install these extensions in WSL (not locally):

ESLint - JavaScript/TypeScript linting
Prettier - Code formatting
GitLens - Enhanced Git capabilities
Docker - Container management
Thunder Client - API testing
Error Lens - Inline error highlighting
Auto Rename Tag - HTML/JSX tag renaming
Path Intellisense - File path autocomplete

To install in WSL, click "Install in WSL: Ubuntu" when viewing an extension.

Workspace Settings

Create a .vscode/settings.json in your project:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "files.eol": "\n",
  "terminal.integrated.defaultProfile.linux": "bash"
}

Debug Configuration

Create .vscode/launch.json for debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Node App",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/index.js"
    }
  ]
}

Working with Different Languages

Python Projects

# Install Python and pip
sudo apt install -y python3 python3-pip python3-venv

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install packages
pip install flask pandas numpy

Install Python extension in VS Code (WSL), and select the interpreter from your virtual environment.

Java Projects

# Install OpenJDK
sudo apt install -y openjdk-17-jdk maven

# Verify installation
java --version
mvn --version

Install Java Extension Pack in VS Code (WSL).

Go Projects

# Install Go
sudo snap install go --classic

# Set up Go workspace
mkdir -p ~/go/{bin,src,pkg}
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc
source ~/.bashrc

Running and Testing Projects

Integrated Terminal

VS Code's integrated terminal runs in WSL automatically:

Press `Ctrl+`` to open terminal
Run commands as you would in Linux
Multiple terminal instances with split view

Running Development Servers

# Node.js/React example
npm install
npm run dev

# Python Flask example
python app.py

# Go example
go run main.go

Access your app from Windows browser at http://localhost:3000 (or whatever port). WSL 2 automatically forwards localhost.

Debugging

Set breakpoints in your code (click left margin)
Press F5 to start debugging
Use Debug Console for REPL
Step through code with F10 (step over) and F11 (step into)

Docker Integration

Install Docker in WSL

# Install Docker Desktop for Windows with WSL 2 backend
# Or install Docker directly in WSL:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Test Docker
docker run hello-world

Docker Compose Projects

# docker-compose.yml
version: '3.8'
services:
  web:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: password

Run with:

docker-compose up

Version Control Workflow

Daily Git Workflow

# Create feature branch
git checkout -b feature/new-feature

# Stage changes
git add .

# Commit
git commit -m "Add new feature"

# Push to remote
git push origin feature/new-feature

Using VS Code Source Control

Click Source Control icon (Ctrl+Shift+G)
Stage changes with + icon
Write commit message
Click ✓ to commit
Click ⋯ menu for push/pull

Performance Optimization

File Watching

For projects with many files, increase file watcher limit:

echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Memory Settings

Create or edit /etc/wsl.conf:

[wsl2]
memory=8GB
processors=4
swap=2GB

Restart WSL: wsl --shutdown in PowerShell.

Troubleshooting Common Issues

VS Code Can't Connect to WSL

# Reinstall VS Code server in WSL
rm -rf ~/.vscode-server
code .

Port Not Accessible from Windows

# Check if service is listening on 0.0.0.0, not 127.0.0.1
netstat -tuln | grep YOUR_PORT

Slow File Operations

Move project from /mnt/c/ to ~/projects/
Exclude node_modules from Windows Defender
Use .gitignore and .dockerignore properly

Advanced Tips

Custom Shell Aliases

Add to ~/.bashrc:

alias gs='git status'
alias gp='git pull'
alias gc='git commit -m'
alias nrd='npm run dev'
alias code-here='code .'

Task Automation

Use VS Code tasks (.vscode/tasks.json):

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start Dev Server",
      "type": "shell",
      "command": "npm run dev",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

Run with Ctrl+Shift+B.

Multi-root Workspaces

Work on multiple projects simultaneously:

File → Add Folder to Workspace
Select WSL folders
Save workspace file

Conclusion

Developing on WSL with VS Code provides a professional, efficient environment that mirrors production Linux servers while maintaining Windows desktop productivity. This setup is ideal for web development, DevOps, data science, and cloud-native applications.

Start simple, experiment with different workflows, and customize your environment to match your development style. The combination of WSL and VS Code is a game-changer for Windows developers working with Linux-based tech stacks.

Ready to elevate your development workflow? At Arion Interactive, we leverage WSL and modern development tools to build cutting-edge web applications and software solutions.