Skip to content

setup.md

Latest commit

 

History

History
190 lines (128 loc) · 6.48 KB

setup.md

File metadata and controls

190 lines (128 loc) · 6.48 KB

Setup

  • Clone the repo and change into the new directory.

    git clone https://github.com/falling-fruit/falling-fruit-web
cd falling-fruit-web

  • Install the node version specified in the .nvmrc file. This is easiest using nvm.

    # Install node version specified in .nvmrc
nvm install
# Use node version specified in .nvmrc
nvm use

  • yarn is already provided (see .yarn/releases). Use it to install dependencies.

    yarn

  • Initialize your private .env file.

    cp example.env .env

  • Set environment variables in .env.

    • REACT_APP_API_URL: URL for falling-fruit-api. Use https://fallingfruit.org/api/0.3 for the production API if you only want to make frontend changes, or http://localhost:3300/api/0.3 (by default) if you are contributing to both backend and frontend.

    • REACT_APP_API_KEY: API key for falling-fruit-api. Use AKDJGHSD for the production API or any value in column api_keys.api_key if running falling-fruit locally (see database seeds).

    • REACT_APP_RECAPTCHA_SITE_KEY: Site key for reCAPTCHA v3. Use 6Ld99kUdAAAAAAB5nCofKrQB6Vp-e5wR42u5TNZZ for the production API or the site key matching the secret key if running falling-fruit-api locally. reCAPTCHA is only required for adding and editing content as an anonymous (unauthenticated) user.

    • REACT_APP_GOOGLE_MAPS_API_KEY: Your own API key for Google Maps Platform.

    • REACT_APP_GOOGLE_ANALYTICS_TRACKING_ID: Tracking ID for Google Analytics. Optional.

  • Additional (top secret) environment variables in .env are needed to sign and release the mobile apps.

    • ANDROID_KEYSTORE_PATH
    • ANDROID_KEYSTORE_PASSWORD
    • ANDROID_KEYSTORE_ALIAS
    • ANDROID_KEYSTORE_ALIAS_PASSWORD

  • Additional .env.android and .env.ios files are used to set platform-specific environment variables that override those in .env when building for that platform.

Web app

  • Start the application.

To run the app in a browser:

yarn start

Then browse to http://localhost:3000. The app is also available on your local network to test (http-only) on other devices, typically at http://192.168.1.206:3000.

To create a production build (in the build directory):

yarn build

If the build fails due to dependency issues, try starting with a clean install:

rm -rf node_modules
yarn cache clean
yarn

Mobile apps

We use Capacitor to package the web app as Android and iOS apps. Although most of the mobile app can be tested by opening the web app in a narrow browser window, this is inadequate for testing device-specific functionality like permissions, curved layouts, and onboard functions (camera, compass, and GPS).

Bump app versions

Use capacitor-set-version to set the version (e.g., 0.3.0) and integer build number.

npx capacitor-set-version . --version version --build build

Android

android directory · setup · get started

First install the requirements.

  • Android Studio 2024.2.1+
  • SDK Platforms:
    • Android 15 (API Level 35)
  • SDK Tools:
    • Android SDK Build-Tools [35.0.0]
    • Android SDK Command-line Tools [latest]
    • Android SDK Platform-Tools [latest]

Sync the app with any changes to package.json and build output:

yarn build:android
npx cap sync android

Run the app on an emulator or device (see below) and debug with Chrome at chrome://inspect/#devices.

npx cap run android

Alternatively, open as a project in Android Studio:

npx cap open android

Emulators

Follow these instructions to create and manage Android Virtual Devices (AVD) in Android Studio, or use avdmanager from the command line.

Devices

First, enable USB debugging on your device. Then plug the device into your computer, start the adb (Android Debug Bridge) server, and check that the device is listed:

adb start-server
adb devices

Release

Build a signed APK to android/app/build/outputs/apk/release/app-release-signed.apk.

npx cap build android

It can be installed to a device manually as follows (uninstalling any unsigned version may be needed):

adb start-server
adb install android/app/build/outputs/apk/release/app-release-signed.apk

iOS

ios directory · setup · get started

First install the requirements.

And prepare Xcode for first use:

# Install Xcode Command Line Tools
xcode-select --install
# Accept Xcode license
sudo xcodebuild -license
# Run Xcode first launch tasks
xcodebuild -runFirstLaunch

Sync the app with any changes to package.json and build output:

yarn build:ios
npx cap sync ios

Run the app on an emulator or device:

npx cap run ios

Alternatively, open ios/App/App.xcworkspace in Xcode:

npx cap open ios

To build a release, select "Any iOS Device (arm64)" as the build target, then Product > Archive. Follow the prompts to upload to App Store Connect and submit for review.