Gitpod Setup Guide for Windows 11 with WSL2

This comprehensive guide will help you set up Gitpod for TypeScript Excel development with Office Add-ins on Windows 11 using WSL2.

🚀 Quick Start

Prerequisites

Windows 11 Requirements

Windows 11 (Build 22000 or later)
WSL2 installed and configured
Git for Windows
A Gitpod account (free at gitpod.io)

WSL2 Setup

Open PowerShell as Administrator
Run: wsl --install
Restart your computer
Set WSL2 as default: wsl --set-default-version 2

One-Command Setup

# Clone the repository
git clone <your-repository-url>
cd Devcontainers

# Run the setup script
./scripts/setup-gitpod-windows.sh

# Open in Gitpod
# 1. Push your changes to GitHub
# 2. Go to https://gitpod.io
# 3. Open your repository in Gitpod

📋 Detailed Setup Instructions

Step 1: Windows 11 and WSL2 Setup

Enable WSL2

# Run in PowerShell as Administrator
wsl --install
wsl --set-default-version 2

Verify WSL2 Installation

wsl --list --verbose
# Should show your distribution with version 2

Install Git for Windows

Download from git-scm.com
Install with default settings
Verify installation: git --version

Step 2: Gitpod Account Setup

Go to gitpod.io
Sign up with your GitHub account
Authorize Gitpod to access your repositories
Verify your account is active

Step 3: Repository Setup

Clone and Configure

# Clone your repository
git clone <your-repository-url>
cd Devcontainers

# Run the setup script
./scripts/setup-gitpod-windows.sh

# Check the configuration
./scripts/setup-gitpod-windows.sh --test

Push to GitHub

git add .
git commit -m "Add Gitpod configuration for TypeScript Excel development"
git push origin main

Step 4: Open in Gitpod

Go to gitpod.io
Click "New Workspace"
Select your repository
Wait for the workspace to initialize (2-3 minutes)

🛠️ Gitpod Features

Pre-configured Environment

Node.js 20: Latest LTS version
TypeScript 5.0+: Latest TypeScript with full Office.js support
Office.js SDK: Complete SDK with TypeScript definitions
VS Code Extensions: All necessary extensions pre-installed
Project Templates: Ready-to-use Excel Add-in templates

Port Forwarding

Port 3000: Main development server
Port 8080: Office Add-in testing and sideloading
Port 9229: Chrome/Edge debugging port

VS Code Extensions

Office Add-in development tools
TypeScript and JavaScript support
ESLint and Prettier for code quality
Git integration and GitHub support
Testing frameworks (Jest, Playwright)
Web development tools

🎯 Development Workflow

Starting Development

Open in Gitpod: Your workspace will automatically set up
Start Dev Server: Run npm run dev-server
Access Your App: Click the preview URL in Gitpod
Start Coding: Begin developing your Excel Add-in

Creating New Projects

# Create a new Excel Add-in project
./scripts/setup-project.sh my-excel-addin

# Navigate to your project
cd projects/my-excel-addin

# Start development
npm run dev-server

Available Commands

# Development
npm run dev-server    # Start development server
npm run build         # Build for production
npm run build:dev     # Build for development

# Testing
npm test              # Run all tests
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage

# Code Quality
npm run lint          # Run ESLint
npm run lint:fix      # Fix ESLint issues
npm run format        # Format code with Prettier

# Office Add-in Specific
npm run validate      # Validate Add-in manifest
npm run sideload      # Sideload Add-in to Excel

📱 Office Add-in Development

Sideloading Add-ins

Method 1: Using the Command Line

# Build your add-in
npm run build

# Sideload to Excel
npm run sideload

Method 2: Manual Sideloading

Build your add-in: npm run build
Create a manifest.xml file
In Excel, go to Insert > Add-ins > Upload My Add-in
Select your manifest file

Testing in Excel Online

Start your dev server: npm run dev-server
Open Excel Online
Go to Insert > Add-ins > Upload My Add-in
Enter your manifest URL: https://your-gitpod-url/manifest.xml

Testing in Excel Desktop

Ensure your add-in is accessible via HTTPS
Use the sideloading method above
Your add-in will appear in the Insert tab

🔧 Configuration Files

.gitpod.yml

Main Gitpod configuration file containing:

Docker image specification
Port forwarding configuration
VS Code extensions
Environment variables
Workspace tasks

.gitpod.Dockerfile

Custom Docker image with:

Node.js 20
TypeScript toolchain
Office.js development tools
Pre-configured workspace

package.json

Project configuration with:

Gitpod-specific scripts
Office.js dependencies
Development tools
Build and test configurations

🐛 Troubleshooting

Common Issues

WSL2 Not Working

# Check WSL version
wsl --list --verbose

# Update WSL
wsl --update

# Set default version
wsl --set-default-version 2

Gitpod Connection Issues

Check internet connectivity
Verify Gitpod account status
Try refreshing the workspace
Check browser console for errors

Office.js Not Loading

Ensure you're using HTTPS
Check manifest.xml configuration
Verify Office.js CDN accessibility
Check browser console for errors

Build Failures

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check for TypeScript errors
npx tsc --noEmit

Port Issues

Check if ports are already in use
Verify port forwarding in Gitpod
Try different ports in webpack.config.js

Getting Help

Check Documentation:
Community Support:
- Gitpod Community
- Office Add-ins Community
Repository Issues:
- Open an issue in this repository
- Check existing issues and solutions

🚀 Advanced Configuration

Custom Docker Image

Edit .gitpod.Dockerfile to customize the environment:

# Add custom packages
RUN apt-get update && apt-get install -y your-package

# Install additional Node.js packages
RUN npm install -g your-global-package

Additional Ports

Add ports to .gitpod.yml:

ports:
  - port: 3001
    onOpen: open-preview
    name: "Additional Service"
    description: "Custom service port"

Environment Variables

Add to .gitpod.yml:

env:
  - name: CUSTOM_VAR
    value: "custom-value"
  - name: API_KEY
    value: $API_KEY  # From Gitpod secrets

Custom VS Code Settings