Building a react native app in WSL2

rearct-native-app-in-wsl2.md

Building a react native app in WSL2

Install, build and debug a react native app in WSL2 (Windows Subsystem for Linux) and Ubuntu.

• Install tools in Windows
• Enable mirrored networking mode in WSL2
• Install tools in WSL2
• Connect to android hardware device from Windows
• Connect to android hardware device from WSL2
• Connect to android virtual device in Windows
• Create react native app in WSL2
• Build app in WSL2
• Debug app in Visual Studio Code from WSL2

Install tools in Windows

• Install WSL2 and Ubuntu, see here
• Install Android Studio, see here
• Install Viusal Studio Code, see here

Enable mirrored networking mode in WSL2

Mirrored mode networking has the goal of 'mirroring' the network interfaces that you have on Windows into Linux. All programs on Windows and Linux can connect via localhost.

Add the following lines to %UserProfile%/.wslconfig (thanks to @craigjones-dev)

[wsl2]
networkingMode=mirrored
hostAddressLoopback=true

Install tools in WSL2

• Install java-21-openjdk in WSL2 (sudo apt-get install openjdk-21-jre)
• Install Android SDK cmdline tools in WSL2, see here and adjust directory structure, see here
• Install nodejs in WSL2, see here

Set environment variables in .profile or .bash_profile

export ANDROID_HOME=/home/xxx/Android/cmdline-tools/latest
export ANDROID_SDK_ROOT=/home/xxx/Android

PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools
PATH=$PATH:$ANDROID_HOME/bin

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

Connect to android hardware device from Windows

To debug on a hardware device connect to android device via adb

• start adb server in Windows: adb kill-server && adb server start

Connect to android hardware device from WSL2

To debug on a hardware device connect to android device via usbip and adb from WSL2 (thanks to @cjshearer):

• Connect USB device to WSL
• start adb server in WSL2: adb kill-server && adb server start

Connect to android virtual device in Windows

To debug on a virtual device

• create a virtual device in windows with Android Virtual Device Manager, see here
• start the Android Emulator, see here, the adb server automatically starts on Windows.

Create react native app in WSL2

npx react-native init AwesomeProject

Build app in WSL2

Start metro JavaScript bundler and bind to an ipv4 address to enable port forwarding to windows

npx react-native start --host 127.0.0.1

Build app, set device as parameter deviceId from result of adb devices

• deviceId emulator: emulator-5554

npx react-native run-android --variant=debug --deviceId <deviceId>

Debug app in Visual Studio Code from WSL2

Start vs code in WSL2

code .

and install extensions for VS Code

• Remote - WSL
• React Native Tools

VS Code UI runs in windows and the VS Code Server runs in WSL2, see here

Add a launch configuration in file launch.json with specified type and request

"name": "Attach to packager",
"cwd": "${workspaceFolder}",
"type": "reactnative",
"request": "attach"

Build app, attach to packager and start debugging, see here.

Good news, using the new mirrored mode networking feature of WSL2, the setup part for connecting the device or emulator to the project server is now simpler.

1. enable mirrored mode networking through the .wslconfig file (usually located in C:\Users\<user_name>)

[wsl2]
networkingMode=mirrored

2. add this in the rc file (eg. .bashrc), so that when we run the project in wsl it uses the adb in windows

### Make alias for adb in Windows so that it can be called within WSL
alias adb="/mnt/c/Users/<user_name>/AppData/Local/Android/Sdk/platform-tools/adb.exe"

thats pretty much it.

Also make sure the firewall isn't the way by adding inbound rules with the ports for adb (5037) and the project server (usually 8081)

Before I had to add export WSL_HOST_IP="$(tail -1 /etc/resolv.conf | cut -d' ' -f2)", export ADB_SERVER_SOCKET=tcp:$WSL_HOST_IP:5037 and export REACT_NATIVE_PACKAGER_HOSTNAME=$(ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}') in the rc file. And to connect my physical device and the project server I had to run adb kill-server and adb -a nodaemon server start in windows first, every time I want to start the project.

Now with this we can just start the project directly and it should now connect to the physical device.

Big thanks for the people who contributed to this guide, hope this helps someone.

Ok so after a few days I've realized that this only works if I type adb devices in wsl terminal before starting the expo project, this is because I had 2 copies of adb, one in wsl and the other in windows, and this starts the adb server in windows.

After digging through the source code of expo, found out that expo checks if adb server is already running, if it is, it uses that server, this explains why running the adb server in windows then starting the expo project in wsl works. We can also see that in assertSdkRoot() (source) it tries to find the adb through the environment variable $ANDROID_HOME, so this explains why when we start the project it still runs the adb in wsl.

In order for us to no longer do the extra step of starting the adb server in windows through typing adb devices or adb start-server in wsl terminal before we start the project, a hacky way to fix this is to make a symlink (not really the same but think of it as a shortcut file windows but in linux) in the platform-tools folder in wsl that points to the adb in windows.

Type this is wsl terminal:

ln -s /mnt/c/Users/<user_name_windows>/AppData/Local/Android/Sdk/platform-tools/adb.exe /home/<user_name_wsl>/Android/platform-tools/adb

with this, we've eliminated the extra step, now we can just start the project in wsl and it should connect to your physical device 😄

Good news, using the new mirrored mode networking feature of WSL2, the setup part for connecting the device or emulator to the project server is now simpler.

1. enable mirrored mode networking through the .wslconfig file (usually located in C:\Users\<user_name>)

[wsl2]
networkingMode=mirrored

2. add this in the rc file (eg. .bashrc), so that when we run the project in wsl it uses the adb in windows

### Make alias for adb in Windows so that it can be called within WSL
alias adb="/mnt/c/Users/<user_name>/AppData/Local/Android/Sdk/platform-tools/adb.exe"

thats pretty much it.
Also make sure the firewall isn't the way by adding inbound rules with the ports for adb (5037) and the project server (usually 8081)
Before I had to add export WSL_HOST_IP="$(tail -1 /etc/resolv.conf | cut -d' ' -f2)", export ADB_SERVER_SOCKET=tcp:$WSL_HOST_IP:5037 and export REACT_NATIVE_PACKAGER_HOSTNAME=$(ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}') in the rc file. And to connect my physical device and the project server I had to run adb kill-server and adb -a nodaemon server start in windows first, every time I want to start the project.
Now with this we can just start the project directly and it should now connect to the physical device.
Big thanks for the people who contributed to this guide, hope this helps someone.

Ok so after a few days I've realized that this only works if I type adb devices in wsl terminal before starting the expo project, this is because I had 2 copies of adb, one in wsl and the other in windows, and this starts the adb server in windows.

After digging through the source code of expo, found out that expo checks if adb server is already running, if it is, it uses that server, this explains why running the adb server in windows then starting the expo project in wsl works. We can also see that in assertSdkRoot() (source) it tries to find the adb through the environment variable $ANDROID_HOME, so this explains why when we start the project it still runs the adb in wsl.

In order for us to no longer do the extra step of starting the adb server in windows through typing adb devices or adb start-server in wsl terminal before we start the project, a hacky way to fix this is to make a symlink (not really the same but think of it as a shortcut file windows but in linux) in the platform-tools folder in wsl that points to the adb in windows.

Type this is wsl terminal:

ln -s /mnt/c/Users/<user_name_windows>/AppData/Local/Android/Sdk/platform-tools/adb.exe /home/<user_name_wsl>/Android/platform-tools/adb

with this, we've eliminated the extra step, now we can just start the project in wsl and it should connect to your physical device 😄

@Se7enSe7enSe7en
I installed Windows 10 because I dont want BSOD for Win 11
I am trying to run a -Bare React Native Project- and not React-Expo

Have you tested your mirrored mode networking to see if it works for Bare React Native?

My head is really spinning at this point from reading so many threads
when i apply the configs of a particular thread, it results in another error
and now i am entrapped in a vicious loop

Can you create your own New Gist and simply link to it here?
I ask this because i am unsure of how to setup my dev environment following the configs in this current gist alongside this mirrored mode networking feature

It seems expo.fyi is updated with a simple .wslconfig:

[wsl2]
networkingMode=mirrored
[experimental]
hostAddressLoopback=true

Working well compared to all the hacky methods I've tried in the last year or so.

@craigjones-dev thanks, now there is a much simpler workflow.

React Native + Expo on WSL2 — Arch

Install Android SDK Command-line Tools

1. Install android-sdk-cmdline-tools-latest, jdk and optional dependencies (Arch Linux example):

yay -S android-sdk-cmdline-tools-latest android-sdk-platform-tools jdk-openjdk

Confirm installation:

which sdkmanager
sdkmanager --version

Configure Environment Variables in WSL2

Add the following to ~/.zshrc or ~/.bashrc:

# Android SDK
export ANDROID_HOME=/opt/android-sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

Apply changes:

source ~/.zshrc or source ~/.bashrc

Set permissions for Android SDK directory:

sudo chown -R $USER:$USER /opt/android-sdk

Accept SDK licenses and install packages

# Install platform-tools, SDK platforms, build-tools
sdkmanager --install "platform-tools" "platforms;android-36" "build-tools;36.0.0"

# Accept all licenses
yes | sdkmanager --licenses

Verify installation:

adb version
ls $ANDROID_HOME/platforms

Connect your phone via USB (initial setup)

Enable Developer Options → USB debugging on your phone.

Connect via USB. Set phone to Transferring files (MTP).

Setup Metro bundler for LAN access

Find Windows host IP on Wi-Fi:

ipconfig

Find WSL2 IP:

ip addr

Forward port 8081 from Windows → WSL2:

netsh interface portproxy add v4tov4 listenaddress=192.168.xxx.xxx listenport=8081 connectaddress=172.18.xxx.xxx connectport=8081

Allow port 8081 through Windows firewall:

• Open Windows Defender Firewall → Advanced Settings → Inbound Rules → New Rule → Port → TCP → 8081 → Allow → Private → Finish

Enable ADB over Wi-Fi

Find your phone’s Wi-Fi IP:

Settings → Connections → Wi-Fi → gear icon → Advanced → IP address

Connect via Wi-Fi:

adb tcpip 5555
adb connect 192.168.xxx.xxx:5555
adb devices

Phone is now connected over Wi-Fi.

Create and start a React Native / Expo project

# Create new Expo app
npx create-expo-app@latest

# Start Metro bundler
npm start

Metro should show:

Metro waiting on exp://192.168.xxx.xxx:8081

Hi! Does someone actually manage to make it work with WSL2 and emulated devices?

@wuleninja try using wsl with network on mirror mode and u can run whatever emulator u want

I found that the official documentation states that the minimum system for mirror mode is Windows 11

Title: Using WiFi for RN Debugging in WSL2 (Mirrored Network Environment)

Prerequisites:

• Ensure WSL2 is running in a mirrored network environment.
• Enable Wireless debugging in the Developer Options on your phone.

Connection Steps:

1. Pair the device using a pairing code:
   adb pair <device_ip>:<pairing_port>
   Enter the matching pairing code when prompted. You should see Successfully paired.
2. Connect to the device:
   adb connect <device_ip>:<port>
   You should see connected to <device_ip>: indicating success.
3. Verify the connection:
   adb devices
   The output should list your device as: <device_ip>: device

React Native App Configuration (on the phone):

1. Shake the phone to open the Dev Menu.
2. Tap Dev Settings.
3. Tap Debug server host & port for device.
4. Enter: localhost:8081

Start the Metro Bundler

@AdalZayas I was already using the mirror mode. Even though adb devices shows an emulator device - with adb in the SDK actually pointing to Windows' adb.exe version (through a symlink), gradle does not seem to be able to work with it. I get this loop forever:

2025-12-10T22:22:02.179+0100 [INFO] [org.gradle.api.Task] [DeviceMonitor]: adb restarted
2025-12-10T22:22:03.254+0100 [INFO] [org.gradle.api.Task] [DeviceMonitor]: adb restarted
2025-12-10T22:22:04.328+0100 [INFO] [org.gradle.api.Task] [DeviceMonitor]: adb restarted
...
2025-12-10T22:22:27.972+0100 [INFO] [org.gradle.api.Task] [DeviceMonitor]: adb restarted

And yet the Windows firewall is disabled.

I give up on this hybrid solution.

With WSLg and nested virtualization, it looks like a full WSL2 solution can be tested. Otherwise, I can still go full Linux, in dual boot or maybe through Virtualbox.

@wuleninja when i was working with this i was using adb but directly on the WSL. This will read some required envs from wsl to run.

I know is kinda tricky to run. It happened to me that some day it was working fine and sometimes not