Set up Ubuntu WSL to develop on Windows

Introduction

I develop in the Windows Subsystem for Linux (WSL 2). Microsoft recommends using WSL 2 if you are using Node.js professionally.

If you are using Node.js professionally, find performance speed and system call compatibility important, want to run Docker containers that leverage Linux workspaces and avoid having to maintain both Linux and Windows build scripts, or just prefer using a Bash command line, then you want to install Node.js on the Windows Subsystem for Linux (more specifically, WSL 2).

Using Windows Subsystem for Linux (WSL), enables you to install your preferred Linux distribution (Ubuntu is our default) so that you can have consistency between your development environment (where you write code) and production environment (the server where your code is deployed).

— Microsoft Docs

Read more about the Windows Subsystem for Linux if you aren't sure about whether you want to use it or not.

tip

Read through each section before you start the steps in it.

This page is mostly links to other docs accompanied by annotations. Reading the annotations can help you get through the other docs.

Install WSL

1. Update to the latest version of Windows 10. Some earlier versions of Windows do not support WSL 2
2. Install WSL on Windows
   1. Remember to update the WSL kernel
   2. Choose Ubuntu 20.04 LTS
   3. Your username doesn't have to be the same as your Windows username. I like to choose me because it's short and saves space on the terminal
   4. Choose a password that's easy to type. Save it in your password manager in case you forget it
3. Install Windows Terminal
   1. Windows Terminal provides nice customization and works better than the terminal built into the Ubuntu WSL
   2. Choose Ubuntu 20.04 as your default profile for Windows Terminal
      1. Open Windows Terminal
      2. Press Ctrl+, to open the Settings
      3. Click Startup on the left
      4. Change your Default profile to Ubuntu-20.04
   3. Update your starting directory for Ubuntu 20.04
      1. Open Windows Terminal
      2. Press Ctrl+, to open the Settings
      3. Click Ubuntu-20.04 on the left
      4. Change your Starting directory to \\wsl$\Ubuntu-20.04\home

Install Node.js on WSL

Follow Microsoft's docs on how to install Node.js on Windows Subsystem for Linux (WSL2)

1. In step 3, use the latest install scripts for nvm
2. After step 3, add nvm to your .bash_profile. The script to install nvm adds it to your .bashrc, but you need it in your .bash_profile as well
   1. Type sudo nano ~/.bash_profile into your terminal and press Enter
   2. Paste the code snippet at the bottom
      Add to ~/.bash_profile

      export NVM_DIR="$HOME/.nvm"
      [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
      [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

   3. Press Ctrl+O to initiate writing the file out
   4. Press Enter to write the file out
   5. Press Ctrl+X to close the file
   6. See the difference between .bash_profile and .bashrc
3. Skip step 6. Follow step 7 by running nvm install --lts

Install VS Code Extensions

1. Remote Development pack
   1. Includes Remote-WSL, which is essential for using your WSL
2. Nodejs Extensions pack for Node.js development
   1. Includes ES Lint for linting JavaScript
3. Prettier for code formatting
4. Code spell checker for spellchecking
5. Rewrap for a keyboard shortcut to hard wrap files (Alt+Q)

Set up Git

Git comes pre-installed on Ubuntu 20.04. If you use a different Linux distribution, you may need to set up Git

1. Tell Git your name

   git config --global user.name "Your Name"

2. Go to github.com/settings/emails, scroll to Keep my email addresses private to find your GitHub email, then tell Git your GitHub email

   git config --global user.email "[email protected]"

3. Set up commit signature verification
   1. Generate a new GPG key for commit signing
   2. Add the key to your GitHub account
   3. Tell Git about your signing key

      git config --global user.signingkey 4AEE18F83AFDEB23

      Remember to do step 5 by adding your GPG signing key to your bash profile
      1. Type sudo nano ~/.bash_profile into your terminal and press Enter
      2. Paste export GPG_TTY=$(tty)
      3. Press Ctrl+O to initiate writing the file out
      4. Press Enter to write the file out
      5. Press Ctrl+X to close the file
   4. Tell Git to always sign commits

      git config --global commit.gpgsign true

4. If you need a reminder on how to use Git, read the GitHub Guides

Set up your SSH key

Follow GitHub's docs on how to set up your SSH key

1. Generate a new SSH key
   1. Choose a password that's easy to type. Save it in your password manager in case you forget it
2. Add a new SSH key to your GitHub account
3. Test your SSH key

Check the configs

1. Open Windows Terminal
2. Type cd ~ and press Enter to return to the home directory
3. Type code . and press Enter to open Visual Studio Code

.bash_profile

Your .bash_profile should have at least these lines

export GPG_TTY=$(tty)

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

.gitconfig

Your .gitconfig should have at least these lines

[user]
    email = [email protected]
    signingkey = 4AEE18F83AFDEB23
    name = Theodore Chu
[commit]
    gpgsign = true

Optional

1. If you need to use Docker, Set up Docker for WSL 2. You need to run WSL as Administrator if you want to use Docker 8.