Quickstart

Get Space7 running on Android from scratch in under 10 minutes.

This guide walks you through cloning the Space7 repository and launching the app on an Android emulator or physical device. By the end you will see the app’s auth screen on your device.

Space7 targets Android only. An ios/ directory exists in the repo (generated by the React Native template) but iOS builds are not maintained. Follow this guide using an Android emulator or a physical Android device.

Prerequisites

Before you begin, confirm the following tools are installed and configured on your machine.

Requirement	Minimum version	Notes
Node.js	>= 22.11.0	Required by the engines field in package.json
npm	Bundled with Node.js	Used as the package manager
JDK	17	Required by Android Gradle
Android Studio	Latest stable	Provides the SDK, emulator, and platform tools
Android SDK	API 33+ recommended	Installed through Android Studio SDK Manager

If you need help installing these tools, see the Environment Setup guide.

---

1. Clone the repository

   Clone the Space7 repository and navigate into the project directory.

   git clone <your-repo-url>
   cd space7
   

   Replace <your-repo-url> with the actual remote URL for your Space7 repository.

2. Install dependencies

   Install all Node.js dependencies using npm.

   npm install
   

   This installs runtime dependencies (React Native, React Navigation, socket.io-client, etc.) and dev dependencies (TypeScript, Biome, Jest, Husky).

   npm >= 22.11.0 of Node.js is enforced by the engines field in package.json. If you see an engine mismatch error, upgrade Node.js before continuing.

3. Configure environment variables

   Space7 reads its backend API endpoint from a .env file at the project root. The app’s network constant is defined in src/constants/Network.ts and pulled in through react-native-dotenv.

   Create a .env file in the project root:

   touch .env
   

   Then add your server endpoint:

   SERVER_ENDPOINT=http://192.168.1.100:3000
   

   Replace the value with the URL of your actual backend. When running on a physical device or emulator, use your machine’s local network IP address rather than localhost, because localhost inside the app refers to the device itself.

   The allowUndefined option for react-native-dotenv is set to false in babel.config.js. If SERVER_ENDPOINT is missing from .env, the Metro bundler will throw an error at startup. Make sure the .env file exists and contains a value before running the app.

4. Start an Android emulator or connect a device

   You need a running Android target before building the app. Choose one of the following:

   Option A — Android emulator

   Open Android Studio, go to Device Manager, and start a virtual device (AVD). Wait until the emulator finishes booting before proceeding.

   Option B — Physical device

   Enable USB debugging on your Android device (Settings → Developer Options → USB Debugging), then connect it via USB.

   Verify that your target is visible to ADB:

   adb devices
   

   You should see output similar to:

   List of devices attached
   emulator-5554   device
   

   If no devices appear, make sure USB debugging is enabled and that ADB platform-tools are on your PATH. See the Environment Setup guide for troubleshooting steps.

5. Start the Metro bundler

   Open a terminal in the project root and start the Metro JavaScript bundler.

   npm run dev
   

   Metro will print a QR code and a local URL (e.g. http://localhost:8081). Leave this terminal running — Metro must stay active while you develop.

   If Metro reports that the port is already in use, stop the existing Metro process and rerun npm run dev.

6. Run the app on Android

   In a second terminal, build and deploy the app to your connected device or emulator.

   npm run android
   

   This runs react-native run-android under the hood, which triggers a Gradle build and installs the debug APK on your target device. The first build typically takes 2–5 minutes. Subsequent builds are faster thanks to Gradle’s incremental build cache.

   If the build fails after adding a new native dependency or changing Gradle configuration, run the clean build command instead:

   npm run android:clean
   

   This removes stale Gradle artifacts and relaunches the app from a clean state.

7. Verify the app launches

   Once the build succeeds, the Space7 app opens automatically on your device or emulator. You should see the auth screen — the entry point of the app.

   From here you can:

   • Edit any file inside src/ — Metro’s Fast Refresh will apply your changes instantly without a full rebuild.
   • Navigate through the app’s screens: Home, New Topic, My Discussions, My Profile, and Space (opened by tapping any space card).

   Shake the device (or press Ctrl+M in the emulator) to open the React Native developer menu for debugging tools, reload shortcuts, and performance overlays.

Next steps

• Review the Environment Setup guide if you ran into any tooling issues during this quickstart.

• Check the available npm scripts for other useful commands:

  Script	Description
  npm run android	Build and launch on Android
  npm run android:clean	Clean Gradle artifacts and rerun
  npm run dev	Start the Metro bundler
  npm run test	Run the Jest test suite
  npm run biome:run	Run Biome checks and apply safe formatting fixes
  npm run link	Link bundled assets (fonts, images)