Vinicunca

Overview

Set up a fast, Linux-based web development environment on Windows 11 with WSL, zsh, Node.js, pnpm and VS Code.

This guide walks you through turning a fresh Windows machine into a web development workstation. Your code, tools and terminal run inside a real Linux distribution through the Windows Subsystem for Linux (WSL), while your editor, browser and everyday apps stay on Windows.

Who it's for

  • Web developers on Windows who want the same tooling as macOS and Linux teammates (POSIX shell, curl | sh installers, Linux-only npm packages).
  • Anyone setting up a new machine, or cleaning up an old one, to work on Vinicunca projects or any Node.js, Vue or Nuxt codebase.

You need Windows 11 (or Windows 10 version 22H2) with virtualization enabled in the firmware, and an account with administrator rights.

Some steps use features that only exist on newer builds: sudo for Windows needs Windows 11 version 24H2, and mirrored WSL networking needs Windows 11 version 22H2. Check yours with Win + R, then run winver.

What you'll end up with

  • Windows Terminal as the default terminal, opening straight into your Linux home directory.
  • WinGet (and optionally Chocolatey) to install and update Windows apps from the command line.
  • WSL 2 with Ubuntu, systemd enabled and sensible memory and networking settings.
  • zsh with Oh My Zsh (or Starship) as your login shell.
  • Git that signs in through Git Credential Manager or the GitHub CLI, with no passwords stored in plain text.
  • Node.js LTS managed by fnm, switching versions per project automatically.
  • pnpm as your package manager.
  • VS Code connected to WSL, linting and formatting with the Vinicunca ESLint config.

Steps

Follow the pages in order. Each one assumes the previous ones are done.

1. Windows Terminal

Install or update Windows Terminal and make it the default.

2. Package managers

Open an admin shell, then use WinGet (and optionally Chocolatey) to install apps.

3. WSL

Install Ubuntu on WSL 2 and configure memory, networking and systemd.

4. zsh

Replace bash with zsh, Oh My Zsh and a couple of essential plugins.

5. Git

Configure your identity, line endings and secure authentication.

6. Node.js

Install fnm inside WSL and use it to install Node.js LTS.

7. pnpm

Install pnpm with its standalone script.

8. VS Code

Connect VS Code to WSL and set up ESLint, Vue and UnoCSS.

Time estimate

Plan for about 45 to 60 minutes on a reasonable internet connection. Installing WSL requires one reboot, and most of the remaining time is spent waiting for downloads.

Once you're set up, see the Extras for commit message conventions and fixes for common WSL problems.

Windows Terminal

Install Windows Terminal, make it your default terminal and have it open straight into your Linux home directory.