Setup VSCode and WSL
Tags: windows, vscode, wsl, tutorial
Published: 2023-05-31 06:56:27

Just like most of the Front-end folks, I was a loyal MacBook user for the last 7 years. Only util recent months I started coding on my Windows PC with VSCode.

Although the development experience is significantly improved since Windows 10 introduced the Linux subsystem(WSL), I still met problems one after one. Eventually, I found that I went in the wrong direction and the quick solution was right in front of me!🤦‍♀️

In short: **Remote development in WSL with VSCode**.

Here are the simple steps and my exploration with other setups. I hope it helps saving your time. 

## The setup in short

Before we start, please ensure that you have upgraded your Windows 10 to at least version 2004 (According to [the official WSL tutorial](https://learn.microsoft.com/en-us/windows/wsl/install)) for WSL to work.

### Enable the subsystem

There are 2 ways to enable the subsystem. 

From GUI in the “**Turn Windows Features on and off**”:

![https://code.visualstudio.com/assets/docs/remote/wsl-tutorial/windows-features.png](https://code.visualstudio.com/assets/docs/remote/wsl-tutorial/windows-features.png)

Or in the command line tools with administrator according to [the official WSL tutorial](https://learn.microsoft.com/en-us/windows/wsl/install):

```powershell
wsl --install
```

Then you shall be able to find the “WSL” app in the Windows Start Menu.

### Update Ubuntu version

In my experience, the default Ubuntu installed is v16, which is so outdated that I could only install Node.js v14.

With command `wsl --list --online`, you may find a more updated version like `22.04 LTS` in the following screenshot I took few weeks ago:

![WSL distros](https://pbs.twimg.com/media/FuCgS9naYAokowS?format=png&name=small)

You may install it with command:

```powershell
wsl --install -d Ubuntu-22.04
```

Then you shall be able to find the “Ubuntu 22.04 LTS” app in the Windows Start Menu.

### VSCode remote development

Next, install [VSCode](https://code.visualstudio.com/) and the [WSL extension](https://www.notion.so/The-inspiring-extension-systems-design-overview-Chrome-VSCode-59149ac0fce44b1b878a0d6f71f36898), and you will be able to find “Connect to WSL using Distro” in the command palette:

![https://code.visualstudio.com/assets/docs/remote/wsl-tutorial/wsl-commands.png](https://code.visualstudio.com/assets/docs/remote/wsl-tutorial/wsl-commands.png)

Select the `Ubuntu-22.04` you have just installed:

![Choose WSL distro](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i6ode205ezjrdiw8a26o.png)

A new VSCode window will open in a remote mode working on the Ubuntu file system, and you may happily coding there just like working locally. The only noticeable latency I found so far is in the starting up.

## Why remote development in WSL

I started local development with WSL as a terminal because quite a few things couldn’t work well under Windows. And soon the nightmares came to me:

- Splitting terminal failed
- Extension like Jest debugger, prettier spoiled
- Watching mode broken
- HMR died

Maintaining VSCode extensions was still tolerable, while it was nearly impossible for me to work on a web app. 

I noticed the root cause of these malfunctions was **path**. Afterall, Windows and the subsystem Ubuntu are running on **2 different file systems** no matter how seamlessly WSL looks:

- All the Windows drives will be mounted under `/mnt/` folder in WSL.
- All the [localhost](http://localhost) ports will be forwarded without extra configurations.

However, if we operate the VSCode in Windows, the IDE and their extensions expect working with Windows file system not the Linux’s. As for stuff like HMR not working, I haven’t dived deep into it but I guess something to do with the port forwarding setups.

I believe most people will choose to code in Linux but play in Windows just like me :) (Or you can just buy a powerful but expensive MacBook).

You may wonder why not using a docker image for the remote development? Well, docker image is a great choice if you are not planning to run another docker instance in it. In my case, I sometimes setup things such as DB with docker image. 

And I tried to walk away from the environment issue with web IDEs such as GitHub Workspace, Replit, Stackbliz, CodeSandbox before thinking of remote. They are the fast-acting drug worth to take a shot in my mind. However, the web IDE crashed frequently when my experiment grew bigger, and some IDEs demand for a “pro” upgrade to get better experience while the Copilot I paid is not available there. 

## Final thought

I made a mistake of trying to live with the situation and soon it backfires. It is important to get the tools work right enable to get the job done.