Skip to content
Astroship.ai Docs

Setting up for local Windows development

Development on Windows requires specific configuration using Windows Subsystem for Linux (WSL). This guide will help you set up your Windows environment correctly to avoid common issues.

1. Enable WSL

First, enable the required Windows features:

  1. Open Start Menu -> Settings -> Optional features -> More Windows features
  2. Check these boxes:
    • “Windows Subsystem for Linux"
    • "Windows Sandbox”
  3. Click OK and restart when prompted

2. Install WSL

  1. Open PowerShell as Administrator
  2. Ensure you have the latest WSL:
Terminal window
wsl --update
  1. Install WSL:
Terminal window
wsl --install

3. First-Time Ubuntu Setup

After WSL installation completes:

  1. Open Start Menu and launch Ubuntu
  2. Create your Linux username and password when prompted
  3. Update the system:
Terminal window
sudo apt update && sudo apt upgrade -y

4. Install Windows Terminal

  1. Install Windows Terminal Preview from: https://aka.ms/terminal ↗
  2. Configure settings:
    • Click the chevron (▼) next to tabs
    • Go to Settings -> Startup
    • Set “Default profile” to Ubuntu
    • Set “Default terminal application” to Windows Terminal Preview

5. Configure Node.js in WSL

Launch Windows Terminal and run these commands:

Terminal window
# Install build dependencies
sudo apt-get install -y build-essential curl git


# Install nodenv
git clone https://github.com/nodenv/nodenv.git ~/.nodenv
sudo ln -vs ~/.nodenv/bin/nodenv /usr/local/bin/nodenv


# Compile dynamic bash extension (can safely fail)
cd ~/.nodenv && src/configure && make -C src || true
cd ~/


# Add nodenv to PATH and initialize
echo 'export PATH="$HOME/.nodenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(nodenv init -)"' >> ~/.bashrc
source ~/.bashrc


# Install plugins
mkdir -p "$(nodenv root)"/plugins
git clone https://github.com/nodenv/node-build.git "$(nodenv root)"/plugins/node-build
git clone https://github.com/nodenv/nodenv-aliases.git $(nodenv root)/plugins/nodenv-aliases


# Install Node.js
nodenv install 20.12.1
nodenv global 20


# Configure system-wide access
sudo ln -vs $(nodenv root)/shims/* /usr/local/bin/

6. Configure VS Code

  1. Install VS Code from https://code.visualstudio.com/download ↗
    • During installation, ensure “Add to PATH” is checked
  2. Install required packages in WSL:
Terminal window
sudo apt-get install wget ca-certificates

  1. Install VS Code extensions:

  2. Connect to WSL:

    • Open Command Palette (CTRL+SHIFT+P)
    • Type “WSL” and select “WSL: Connect to WSL”

7. Project Setup in VS Code

Open your project:

  1. In VS Code, go to File -> Open Folder
  2. Browse to your project directory (use /home/your-username/...)

Install dependencies:

  1. In VS Code, go to Terminal -> New Terminal
  2. Run:
Terminal window
nodenv install -s
npm install --include=dev

Start development server in debug mode:

  1. Select debugger in the left sidebar of VS Code
  2. Click “Start debugging”
  3. If “astro is ready” message is missing:
    • Stop debugging
    • Start debugging again