The proper guide on how to develop for React Native Expo on WSL2 and Windows

Preface

There are sparse resources when it comes to Expo development under WSL. Expo themselves have dedicated a short fyi page to this topic, going into the least amount of detail possible and only concerning how to run a dev server to connect to with Expo Go, the limitations of which are probably clear to all of us.

Then there is this fine article by Mo Akbari, which did push me in the right direction, but did not allow me to run actual dev-builds on the Android emulator running on my Windows host, as Expo would attempt to build the app using the mounted Windows Android SDK directory, to which we pointed our ANDROID_HOME, causing all kinds of problems I have tried to patch up in the most creative ways imaginable.

Solution

The solution is to completely build on WSL, having ANDROID_HOME point to a valid Android SDK on your Linux subsystem and employing a few clever hacks to make a seamless connection to your Android Virtual Devices on the Windows side.

Prerequisites

• JDK 17 and JAVA_HOMEset to its directory containing bin/
• Android commandline tools for Linux archive (zip) downloaded
• (Optional) VSCode on Windows with Remote Development extension pack
• Android Studio installed on Windows, with at least one Virtual Device

If you have set up a Virtual Device and the Android SDK Platform Tools on Windows and/or the proper WSL-side Android SDK already installed, you can skip either of the SDK setup portions.

Windows side SDK setup

1. Open Android Studio SDK Manager (More Actions -> SDK Manager)
2. Install Android SDK Platform-Tools from SDK Tools tab
3. Verify you have a virtual device created and if not, create one (More Actions -> Virtual Device Manager)

WSL side SDK setup

1. Move your downloaded commandlinetools zip archive into ~/android_sdk or a directory of your choice. This will from now on be referred to as ~/android_sdk, so make sure to replace any future occurrence with your chosen directory.

2. unzip the archive (called commandlinetools-linux-*.zip)

3. Add ~/android_sdk as your ANDROID_HOME environment variable

echo -e '\nexport ANDROID_HOME=$HOME/android_sdk' >> ~/.bashrc

4. Add the commandline-tools to your PATH and reload your shell

export PATH=$PATH:$HOME/android_sdk/cmdline-tools/bin && source ~/.bashrc

5. Install the required SDK and packages (you can experiment with leaving out the platform-tools, we’ll delete it later anyways). Should Expo require different platform and build-tool versions in the future, use this command to install them and adapt the version numbers.

sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"

6. Accept all licenses, for Expo to be able to download further dependencies during the build process

yes | sdkmanager --licenses

Making the Magic happen (WSL)

We have now successfully installed a working build environment to build android dev builds on the WSL side. The next part is where the magic happens.

1. If you installed the platform-tools, its now time to delete them from your ~/android_sdk (or where ever your Android SDK resides)

cd ~/android_sdk && rm -rf platform-tools/

2. Create a symlink (symbolic link) from your ~/android_sdk to the platform-tools directory on your Windows side through the WSL mount. Remember to substitute your Windows username here.

ln -s /mnt/c/Users/<username>/AppData/Local/Android/Sdk/platform-tools platform-tools

Making the Magic happen (Windows)

Most of the heavy lifting is done now, but when you initiate an Expo dev-build on WSL it will fail still, because we will have to do some prep work on the Windows side.

In order to be able to run adb and emulator from WSL, we have to copy their Windows executables (.exe) to files of identical names, but without the file extension.

1. Open C:\Users\<user>\AppData\Local\Android\Sdk\ in your explorer
2. Copy …\platform-tools\adb.exe to …\platform-tools\adb
3. Copy …\emulator\emulator.exe to …\emulator\emulator

At this point I can not guarantee, that these are the only executables that have to be copied, as I personally use a small custom setup-script to copy all .exe files in those two directories to a non-exe counterpart!

You might also want to add the mounted Windows-side platform-tools to your $PATH, as I have done, but it should not be required.

export PATH=$PATH:/mnt/c/Users/<username>/AppData/Local/Android/Sdk/platform-tools

Starting an Android Virtual Device on Windows from WSL shell!

You can now also start emulators on Windows from a WSL shell using the very handy command

/mnt/c/Users/<username>/AppData/Local/Android/Sdk/emulator/emulator -avd <device_name>

and list your available devices using

/mnt/c/Users/<username>/AppData/Local/Android/Sdk/emulator/emulator -avd -list-avds

so I will leave what you do with this up to you. You could add the mounted emulator directory to your $PATH, or create scripts to start emulators for you from WSL.

I personally assigned the Windows-side SDK path to an environment variable ANDROID_HOME_WIN and hacked together a little >script in plain js< to list my virtual devices and run the one I select, which I execute through a package.jsoncommand. I added some comments to it for you.

And that’s it!

Start an emulator, do [bun | yarn | npm] expo run:android and you should see Expo building your dev-build and it being launched on your Windows Virtual Android Device.

Just remember to have a virtual device running before starting the build.

Some installs of JDK might cause an issue at first, but setting JAVA_HOME to the correct directory where the bin/ directory containing the java 17 binaries reside will resolve that.