Skip to main content

Environment Setup

Good setup documentation prevents weeks of friction. The objective is not only to get one machine working. The objective is to make onboarding repeatable for every engineer who joins the project.

Baseline requirements​

Most React Native teams standardize on:

  • A current Node.js runtime supported by the toolchain.
  • A package manager such as npm, pnpm, or yarn.
  • Git and a clear branching strategy.
  • A code editor with TypeScript, ESLint, and formatting support.
  • Platform toolchains for Android and, when building iOS apps, macOS with Xcode.

iOS prerequisites​

If the team ships to iPhone or iPad, a macOS environment is required for local iOS builds and simulator work. The setup normally includes:

  • Xcode and the iOS Simulator.
  • CocoaPods for native dependency integration when your workflow requires it.
  • Command line tools enabled from Xcode.

Android prerequisites​

Android development usually requires:

  • Android Studio.
  • Android SDK platforms and build tools that match the project needs.
  • An emulator or a physical device with USB debugging.
  • ANDROID_HOME or equivalent environment configuration if your workflow depends on it.

Helpful supporting tools​

  • Watchman where supported, for reliable file watching.
  • Java aligned with the Android toolchain requirements.
  • A secrets strategy that does not rely on developer machines storing production values locally.

Verification checklist​

Run and verify the basics before generating the application:

node --version
npm --version
java -version
adb devices

On macOS teams shipping iOS:

xcodebuild -version

Framework-led start:

npx create-expo-app@latest my-app

Bare React Native start:

npx @react-native-community/cli@latest init MyApp

Team-level setup standards​

Document these centrally:

  • Which package manager is authoritative.
  • Which Node version the repository expects.
  • Which environment files exist and who owns them.
  • Which local services are required for development.
  • Which commands are the canonical way to start iOS, Android, tests, and linting.

Common setup failures​

Inconsistent Node versions​

If different engineers use different runtimes, native dependency installs and Metro behavior often become inconsistent. Pin the runtime and enforce it in CI.

Hidden native prerequisites​

Teams often document JavaScript setup but forget the native side. Make sure Android SDKs, signing requirements, CocoaPods usage, and Xcode expectations are explicit.

Environment configuration drift​

If local .env files are copied manually from chat messages, the project will rot quickly. Treat configuration as part of the system, not as tribal knowledge.

Definition of done​

Environment setup is complete when a new engineer can clone the repository, install dependencies, boot iOS and Android, run tests, and understand where configuration lives without pairing on every step.

Next, lock in the project structure.