Environment Setup

This guide covers the full Android development environment required to build Space7. Follow every section in order if you are setting up a machine from scratch.

Space7 targets Android only. You do not need to install Xcode, CocoaPods, or any iOS toolchain to build and run the app.

Node.js

Space7 requires Node.js >= 22.11.0. The minimum version is enforced by the engines field in package.json.

macOS
Linux
Windows

The recommended approach on macOS is to use nvm (Node Version Manager), which lets you switch between Node versions easily.

Install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Restart your terminal, then verify the install:

nvm --version

Install Node.js 22

nvm install 22
nvm use 22
nvm alias default 22

Verify

node --version
npm --version

node --version must print v22.11.0 or higher.

Install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Source your shell config to activate nvm:

source ~/.bashrc
# or, if using zsh:
source ~/.zshrc

Install Node.js 22

nvm install 22
nvm use 22
nvm alias default 22

Verify

node --version
npm --version

On Windows, use nvm-windows or install Node.js directly.Option A — nvm-windows (recommended)Download and run the installer from the nvm-windows releases page, then open a new terminal and run:

nvm install 22
nvm use 22

Option B — Direct installDownload the Node.js 22 LTS installer from the official Node.js site and run it.Verify the installation:

node --version
npm --version

JDK 17

Android’s Gradle build system requires JDK 17. Using a different major version will cause Gradle compatibility errors.

macOS
Linux
Windows

Install JDK 17 using Homebrew:

brew install --cask temurin@17

Then add it to your shell profile (~/.zshrc or ~/.bash_profile):

export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH=$JAVA_HOME/bin:$PATH

Reload your shell and verify:

java -version

The output should start with openjdk version "17.

Install the Temurin JDK 17 package:

# Ubuntu / Debian
sudo apt-get install -y wget apt-transport-https
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
echo "deb https://packages.adoptium.net/artifactory/deb $(lsb_release -sc) main" | \
  sudo tee /etc/apt/sources.list.d/adoptium.list
sudo apt-get update
sudo apt-get install -y temurin-17-jdk

Set JAVA_HOME in your shell profile (~/.bashrc or ~/.zshrc):

export JAVA_HOME=/usr/lib/jvm/temurin-17-amd64
export PATH=$JAVA_HOME/bin:$PATH

Reload and verify:

java -version

Download the Temurin JDK 17 MSI installer from adoptium.net and run it.After installation, set JAVA_HOME in System Environment Variables:

Open System Properties → Advanced → Environment Variables.
Under System variables, click New and add:
- Variable name: JAVA_HOME
- Variable value: C:\Program Files\Eclipse Adoptium\jdk-17.x.x.x-hotspot (adjust to your install path)
Append %JAVA_HOME%\bin to the Path variable.

Open a new terminal and verify:

java -version

Android Studio and Android SDK

Android Studio provides the Android SDK, the emulator, and the Gradle toolchain.

Download and install Android Studio

Download Android Studio from developer.android.com/studio and follow the platform-specific installer.During the setup wizard, make sure you select:

Android SDK
Android SDK Platform
Android Virtual Device

Install required SDK packages

Open Android Studio, go to Settings → Languages & Frameworks → Android SDK (or SDK Manager from the Welcome screen).Under the SDK Platforms tab, install at minimum:

Android 13.0 (API 33) or higher

Under the SDK Tools tab, make sure these are installed:

Android SDK Build-Tools
Android SDK Platform-Tools
Android Emulator
Android SDK Command-line Tools (latest)

Click Apply to download and install.

Set ANDROID_HOME and update PATH

The React Native toolchain requires ANDROID_HOME to point to your SDK directory.

macOS / Linux
Windows

Add the following to your shell profile (~/.zshrc, ~/.bashrc, or ~/.bash_profile):

export ANDROID_HOME=$HOME/Library/Android/sdk       # macOS
# export ANDROID_HOME=$HOME/Android/Sdk             # Linux
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Reload your shell:

source ~/.zshrc

Open System Properties → Advanced → Environment Variables.Add a new system variable:

Variable name: ANDROID_HOME
Variable value: C:\Users\<YourUsername>\AppData\Local\Android\Sdk

Then append the following to the Path variable:

%ANDROID_HOME%\emulator
%ANDROID_HOME%\platform-tools

Verify adb is available:

adb --version

Create an Android Virtual Device (AVD)

In Android Studio, open Device Manager and click Create Device.Recommended configuration for Space7 development:

Device: Pixel 7 (or any phone profile)
System Image: API 33 or higher (x86_64 recommended for performance)
RAM: 2 GB minimum

Start the emulator from Device Manager and wait for the home screen to appear before running npm run android.

ADB Setup and Device Verification

adb (Android Debug Bridge) is your primary tool for verifying device connectivity. It is installed with the Android SDK platform-tools.

Verify a connected device or emulator

adb devices

Expected output when a device is ready:

List of devices attached
emulator-5554   device

If your physical device does not appear:

Enable USB Debugging on the device (Settings → Developer Options → USB Debugging).
Change the USB mode to File Transfer (MTP) rather than Charging Only.
Accept the RSA key fingerprint prompt that appears on the device screen the first time you connect.

Restart ADB if devices are not detected

adb kill-server
adb start-server
adb devices

Watchman (macOS only, optional)

Watchman is a file-watching service developed by Meta. React Native’s Metro bundler can use it to track file changes more efficiently on macOS.

brew install watchman

Watchman is optional on macOS and not required on Linux or Windows. Metro falls back to its built-in file watcher if Watchman is not installed.

Verify the full setup

Run the React Native environment doctor to check that all required tools are correctly configured:

npx react-native doctor

This command checks for Node.js, JDK, Android SDK, ANDROID_HOME, and connected devices. Address any issues it reports before proceeding to the Quickstart.

You can also run npx @react-native-community/cli doctor if the short form does not resolve correctly in your environment.

Troubleshooting

`adb: command not found`

adb is not on your PATH. Make sure $ANDROID_HOME/platform-tools is added to your PATH variable and that you have reloaded your shell profile.

export PATH=$PATH:$ANDROID_HOME/platform-tools
source ~/.zshrc
adb --version

`ANDROID_HOME` is set but Android Studio can't find the SDK

Open Android Studio and go to Settings → Languages & Frameworks → Android SDK. Confirm that the Android SDK Location field matches the value of your ANDROID_HOME environment variable. If they differ, update your environment variable to match the path shown in Android Studio.

Gradle sync fails in Android Studio

This usually means a required SDK package is missing or the JDK version is wrong.

Open android/ in Android Studio.
Go to Settings → Languages & Frameworks → Android SDK and confirm the required SDK packages are installed.
Check File → Project Structure → SDK Location to verify the JDK path points to JDK 17.
Click File → Sync Project with Gradle Files and check the Build output for specific error messages.

Node.js version mismatch error from npm install

The engines field in package.json requires Node.js >= 22.11.0. If you see a version mismatch warning or error:

nvm install 22
nvm use 22
node --version   # should print v22.11.0 or higher
npm install

Java version mismatch — Gradle requires JDK 17

If Gradle reports an incompatible JDK, verify which Java version is active:

java -version
echo $JAVA_HOME

If the output does not show version 17, update JAVA_HOME to point to your JDK 17 installation and reload your shell.

Emulator is slow or crashes

Enable hardware acceleration for the emulator:

macOS / Linux: Ensure Intel HAXM or Android Emulator Hypervisor Driver is installed via the SDK Manager under SDK Tools.
Windows: Enable Hyper-V or install HAXM from the SDK Manager.

Also make sure you are using an x86_64 system image rather than an ARM image for faster emulation on x86 host machines.

Metro bundler fails with `SERVER_ENDPOINT` not found

Space7 uses react-native-dotenv to load environment variables. The .env file must exist in the project root and must define SERVER_ENDPOINT.

echo 'SERVER_ENDPOINT=http://192.168.1.100:3000' > .env

Then restart Metro with the cache cleared:

npm run dev -- --reset-cache

Get Started

Core Features

Navigation & Screens

Development

Environment Setup

Node.js

JDK 17

Android Studio and Android SDK

ADB Setup and Device Verification

Verify a connected device or emulator

Restart ADB if devices are not detected

Watchman (macOS only, optional)

Verify the full setup

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Navigation & Screens

Development

Documentation Index

​Node.js

​JDK 17

​Android Studio and Android SDK

​ADB Setup and Device Verification

​Verify a connected device or emulator

​Restart ADB if devices are not detected

​Watchman (macOS only, optional)

​Verify the full setup

​Troubleshooting

Build docs developers (and LLMs) love

Node.js

JDK 17

Android Studio and Android SDK

ADB Setup and Device Verification

Verify a connected device or emulator

Restart ADB if devices are not detected

Watchman (macOS only, optional)

Verify the full setup

Troubleshooting