Windows Setup
Configure WSL2 development environment for Windows machines.
Windows development requires WSL2 (Windows Subsystem for Linux) for compatibility with Node.js tooling and the StarterApp stack. WSL2 provides a Linux environment integrated with Windows applications and file systems.
WSL2 Required
Native Windows command prompts lack compatibility with Unix-based development tools. WSL2 provides Linux performance characteristics while maintaining Windows Terminal and VS Code integration.
WSL2 Installation
Enable WSL2 and install Ubuntu through a single command:
Open PowerShell as Administrator (right-click Start menu, select "Windows PowerShell (Admin)")
Execute the installation command:
wsl --installThe command enables required Windows features, installs WSL2, downloads Ubuntu, and sets WSL2 as the default version.
Restart the computer when prompted. Ubuntu launches automatically after restart.
Create a Linux username (lowercase, no spaces) and password. The password enables sudo commands and remains invisible during entry.
Heads up
The Linux username and password are separate from Windows credentials. Store the password securely for future sudo operations.
Ubuntu Configuration
After WSL2 installation, configure the Ubuntu environment:
Terminal Environment
Accessing Ubuntu
The Ubuntu environment must be accessed correctly to run development commands:
Wrong Terminal Environment
Commands fail in PowerShell or Command Prompt. The terminal must show username@machine:~$ prompt and display "Ubuntu" in the tab title. Linux commands (apt, sudo, pnpm, node) only function in the Ubuntu environment.
VS Code Integration
Installation and Configuration
Connect VS Code to the WSL2 environment for seamless development:
Download and install VS Code from code.visualstudio.com ↗. Enable "Add to PATH" during installation.
Install the WSL extension from the Extensions marketplace (search "WSL" by Microsoft).
Click the connection button in the bottom-left corner of VS Code (green icon with arrows).
Select "Connect to WSL" from the command palette. VS Code reloads and connects to the Ubuntu environment.
Recommended Extensions
Install these extensions in the WSL environment:
Pro Tip
Launch VS Code from the Ubuntu terminal using code . in the project directory. This ensures correct WSL environment context.
File System Guidelines
Working Directory Location
Development must occur within the Linux file system for optimal performance:
# Correct - Linux file system
cd ~/projects
mkdir -p ~/projects
git clone https://github.com/organization/repository.git
cd repository
# Verify location (should show /home/username/projects)
pwdPerformance Impact
Avoid the Windows file system (/mnt/c/Users/...). Operations in the Linux file system (/home/username/...) run significantly faster. Running pwd should display /home/username/projects rather than /mnt/c/....
Windows Terminal Customization
Enhance the terminal experience with Windows Terminal configuration:
Development Workflow
Standard development session pattern:
Open Windows Terminal with Ubuntu profile (or launch Ubuntu from Start menu)
Navigate to project directory:
cd ~/projects/starterappStart development servers:
pnpm devLaunch VS Code from the terminal:
code .Access applications in the browser:
- Marketing:
http://localhost:3000 - Dashboard:
http://localhost:3001
Common Issues
AI Development Integration
The WSL2 environment provides compatibility with AI-assisted development tools. The Linux file system ensures proper behavior for AI agents accessing the codebase through file system operations.
Claude Code, Cursor, and similar AI development tools function correctly when connected to WSL2. The VS Code WSL extension enables AI assistants to read and modify files within the Linux environment.
Next Steps
After completing Windows platform setup:
Environment Setup
Configure service credentials and environment variables for authentication and billing.
AI Onboarding
Run automated setup with AI guidance for dependency installation and first boot.
VS Code Setup
Install extensions and configure VS Code for optimal StarterApp development.