This is an official iNaturalist client written in React Native that will eventually replace our existing iOS and Android apps. Achieving parity with those established apps is taking some time, but we're getting there!
See CONTRIBUTING for guidelines on contributing to this project.
- Xcode 15 or above
- Android and iOS environment setup described in the RN docs
- Run
npm install
- Run
npx pod-install
orcd ios && pod install
from the root directory cp env.example .env.staging
for staging andcp env.example .env
for production and fill in appropriate values. This is not part of the code repo (contains secrets, such as OAuth client ID).- To run on Android, do this
cp android/example-keystore.properties android/keystore.properties
. Fill in the relevant values. If you are a member of iNat staff, get them from another member of iNat Staff. - Add AI Camera model and taxonomy files. The computer vision model and Geomodel files are not part of the code repo, and have to be installed. The app itself will load the model file with the filename specified in a .env file. On Android, the current file names are specified in these env variables
ANDROID_MODEL_FILE_NAME
,ANDROID_TAXONOMY_FILE_NAME
, andANDROID_GEOMODEL_FILE_NAME
. On iOS, the current file names are specified in these env variablesIOS_MODEL_FILE_NAME
,IOS_TAXONOMY_FILE_NAME
, andIOS_GEOMODEL_FILE_NAME
. After a fresh clone of the repo and copying the env.example file (see above), you have to add the files by following these steps:- Add the example model files by executing
npm run add-example-model
. If that does not work continue with the next step. - If the download script fails: The sample model files are available in this
small_model.zip
file. - On Android, these files are named
small_inception_tf1.tflite
andsmall_export_tax.csv
. Create a camera folder within Android assets (i.e.android/app/src/debug/assets/camera
) and place the files there. - On iOS, these files are named
small_inception_tf1.mlmodel
andsmall_export_tax.json
and should be added to theios
folder. - On iOS, in the
ios
folder, copy the Geomodel placeholder filegeomodel.placeholder
togeomodel.mlmodel
. This file is just a placeholder to get the app to build. We'll release a functional Geomodel for development purposes soon.
- Add the example model files by executing
- Optional: Add Geomodel file. If you have access to the model file, you can add it by following these steps:
- Uncomment and set the
ANDROID_GEOMODEL_FILE_NAME
andIOS_GEOMODEL_FILE_NAME
variables in the.env
and.env.staging
files. - On Android, the file Geomodel should be placed in the
android/app/src/debug/assets/camera
folder. - On iOS, the Geomodel file should be placed in the
ios
folder.
- Uncomment and set the
- We're using Husky to automatically run
eslint
before each commit. Runnpm run postinstall
to install Husky locally. - (Staff only) Set up GitGuardian to prevent yourself from committing secrets
- Install
ggshield
- Get a GitGuardian API token from another staff developer and put it in the
GITGUARDIAN_API_KEY
env variable.
- Install
- Run
npm start -- --reset-cache
(npm start
works too, but resetting the cache each time makes for a lot less build issues) - Run
npm run ios
ornpm run android
If you're on staff you can configure the app to read from and write to our staging server. Override API_URL
to a staging API domain, either using local .env.staging
file, or overriding the environment variable when calling npm start
, e.g. API_URL=http://example.com npm start -- --reset-cache
.
We currently have three kinds of tests:
tests/integration
: Tests the integration of multiple modules, e.g. a list of observation that makes requests to a mocked API, persists the response data in local storage, retrieves the data from local storage and renders components.tests/unit
: Tests only specific modules, like a single component, or a hook.e2e
: Tests user interactions on the finished app build running on the iOS simulator (see below).
We're using Jest and React Native Testing Library for most of our tests, factoria and faker.js to generate test data for use with mocks. Local*
model factories represent locally persisted data, while Remote*
factories represent that kinds of records we get from an API or external package.
# Run all tests
npm test
# Run test paths matching a pattern
npm test MyObs
# Run individual tests matching a pattern. Note the `--` to pass arguments to jest
npm test -- -t accessibility
# Update snapshots for a specific path
npm test Button.test.js -- --updateSnapshot
Note that you can run npx jest
as well, but that will omit some environment variables we need to set for the test environment, so for consistent test runs please use npm test
.
Also note that i18next
needs to be initialized in individual test files (haven't figured out a way to await initialization before all tests, plus allowing tests to control initialization helps when testing different locales). Add beforeAll( async ( ) => { await initI18next( ); } );
to a test file if it depends on localized text.
We're using Detox for E2E tests. If you want to run the e2e tests on your local machine, make sure you follow the Detox environment setup instructions.
Then you have to populate E2E_TEST_USERNAME
and E2E_TEST_PASSWORD
in .env
with real iNaturalist login credentials so the e2e test can actually authenticate.
Then you can run the tests:
# Build the app and run the tests
npm run e2e
If you don't have the iOS simulator the e2e tests are configured to use, you may need to create it in XCode 15: Go to Window > Devices and Simulators, click the Simulators tab, click the "+" button in the lower left, and create a simulator that matches the device.simulator.device.type
setting in .detoxrc.js
.
If you have built the app already for a previous test, and just want to run an updated test without changing the app code, you can run npm run e2e:test
.
If you are running into some issues after the tests have been working for some time, try updating applesimutils
with brew update && brew upgrade applesimutils
.
If you want to run the Android tests you need to prepare your environment. Before you dive into the setup, know that alternatively you might find it easier setting up the required local emulator, preferrably an AOSP (Android Open Source Project) version, using Android Studio. Make sure the emulator has the same name as in the .detoxrc.js
file.
Run npm run e2e:build:android && npm run e2e:test:android
to build the APK for testing purposes and install and run it on the emulator with the name as stated in the .detoxrc.js
file.
Source strings are in src/i18n/strings.ftl
and should be in US English. Don't edit the files in src/i18n/l10n/
because they will get overwritten when we pull in translations. All translation is done by volunteers on Crowdin, so please follow these guidelines to make things easier for those generous people.
-
Labels should match content as closesly as possible (without exceeding 100 characters)
-
Bad
collection-project-screen-title = ABOUT COLLECTION PROJECTS
-
Good
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION PROJECTS
-
-
Labels should change when the content changes
-
Bad
-
Old
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION PROJECTS
-
New
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION AND UMBRELLA PROJECTS
-
-
Good
-
Old
ABOUT-COLLECTION-PROJECTS = ABOUT COLLECTION PROJECTS
-
New
ABOUT-COLLECTION-AND-UMBRELLA-PROJECTS = ABOUT COLLECTION AND UMBRELLA PROJECTS
-
-
-
Annotate strings with comments unless the string is very self-descriptive
-
Bad
Change-date = Change date
Is this a verb phrase or a noun phrase? Are we talking about spare change in your pocket?
-
Good
# Label for a button that changes a selected date Change-date = Change date
-
-
Use double-dashes to append extra context to keys and to keep them unique and descriptive. For example, translators might need to translate the word "Unknown" differently if it refers to a place or a taxon, so you might include both
Unknown--place = Unknown
andUnknown--taxon = Unknown
-
Accessibility hints are used by screen readers to describe what happens when the user interacts with an element. The iOS Guidelines define it as "A string that briefly describes the result of performing an action on the accessibility element." We write them in third person singular ending with a period
-
Pluralize text with a count using selectors
-
Bad
x-observations = { $count } observations
-
Good
x-observations = { $count } { $count -> [one] observation *[other] observations }
-
-
Avoid variables when possible. Variables make translation and static code checks harder
-
Bad
quality-grade-with-label = Quality Grade: { $qualityGrade }
-
Good
quality-grade-with-label--research = Quality Grade: Research quality-grade-with-label--needs-id = Quality Grade: Needs ID quality-grade-with-label--casual = Quality Grade: Casual
There are only 3 possible quality grades, so this can just be three separate strings. Translators don't have to worry about the possible values of
$qualityGrade
and it's much easier to check for unglobalized or unused keys.
-
-
Add new strings in English to
src/i18n/strings.ftl
using Fluent syntax, e.g.# Header for a paragraph describing projects ABOUT-PROJECTS = ABOUT # Text describing what projects are projects-description = Projects are really great, probably iNat's best feature.
-
Run
npm run translate
to validate strings and build the JSON files i18next needs to access text in the app -
In a commponent, use the
useTranslation
hook to reference your new string, e.g.import { useTranslation } from "sharedHooks"; const MyComponent = ( ) => { const { t } = useTranslation( ); return ( <View> <Text>{ t( "ABOUT-PROJECTS" ) }</Text> <Text>{ t( "projects-description" ) }</Text> </View> ); };
When components need to be included around interpolated variables, use the
<Trans />
component:Fluent:
Welcome-user = <0>Welcome back,</0><1>{ $userHandle }</1>
Usage:
<Trans i18nKey="Welcome-user" parent={View} values={{ userHandle: currentUser?.login }} components={[ <Subheading1 className="mt-5" />, <Heading1 /> ]} />
We manage translations through Crowdin. Actually updating the translation files should be largely automated, but this is what it looks like to do it manually (you must have the Crowdin CLI installed and have an access token associated with a Crowdin user that can post files to the specified project):
# Upload new strings. Source and destination paths are specified in crowdin.yml
crowdin upload --token YOUR_ACCESS_TOKEN --project-id YOUR_PROJECT_ID
# Download new translations and build for use in the app
crowdin download --token YOUR_ACCESS_TOKEN --project-id YOUR_PROJECT_ID
npm run translate
git add src/i18n/l10n/*
git commit -a -m "Updated translations"
We're using Nativewind, a styling system for React Native based on Tailwind CSS. Check the Nativewind documentation to see what styles can be used in RN.
We have a custom set of icons stored as SVG files and compiled into a font. New icons should be included with issues in a ready-to-use form, but some editing may be required.
- Add / edit SVGs to / in
src/images/icons/
(git add
any new icons). Icon SVGs must meet the following requirements
<svg>
element must havewidth="24"
andheight="24"
attributes- No paths with
fill-rule="evenodd"
attribute orfill-rule: evenodd styles
npm run icons
- Rebuild the app (you'll have newly-linked assets that won't hot reload)
- Run
npx react-native clean-project
. This will give you options to clean caches, clean builds, reinstall pods, and reinstall node_modules. Using this eliminates a lot of hard-to-diagnose build issues. - If you're running on an M series chip, you may need to install a specific version of NDK to the app to build for Android. See
android/build.gradle
We use fastlane to help automate parts of the deployment process, which requires some additional setup.
- Make a Github personal access token with repo access in the
GITHUB_API_TOKEN
environmental variable. cp android/example-keystore.properties android/keystore.properties
and fill in the relevant values provided by another member of iNat staff.cp fastlane/example-Appfile fastlane/Appfile
and fill in the relevant values provided by another member of iNat staff.- Work with iNat staff to either get a new Apple ID or associate an existing one with the iNat Apple development team
- Sign in to Xcode with your Apple ID
- Manage Certificates and add an Apple Distribution certificate associated with the iNaturalist team
The current expectation is that we tag to freeze the code, bump the internal build number, and describe the changes represented by the tag. Then we release to make builds and publish on Github. Later, presumably when some of the change logs have been translated, we push builds for internal testing. If that looks ok, we push to public testing, and later to production release.
# Make a git tag. This will bump the build number and prompt you to describe
# what changed, which will be used for the eventual github release
# description and changelogs uploaded to the app stores.
fastlane tag
# Make a github release. This will make relevant builds, a github release, and
# add build files to the release
fastlane release
# Upload the build for the latest tag for internal testing
fastlane internal
# Upload the build for the latest tag for public testing (promotes latest
# internal build to open testing)
fastlane beta
# Set up in a production release in app stores, so in the App Store, it
# creates a distribution version based on the latest tag. At present the only
# attributes it updates are the version and copyright. To choose a build and
# submit for review you'll need to use the App Store
fastlane prod
- Ensure all tests are passing on the main branch
- Review and resolve security alerts
- Manual testing
- Install a "Release" build on an iOS device
- Online
- Sign out if already signed in
- Make an observation using the AI Camera
- Delete the observation you just made
- Go to Explore and view a taxon
- Change to observations view and view an observation
- Go to the observers profile
- Go to one project this user joined (if not available try another user)
- Sign in
- Make an observation by taking a new photo in the AI Camera; tap "Upload Now" to upload immediately; wait for upload to complete before moving on
- Make an observation by taking a new photo in the StandardCamera; save without upload
- Make an observation by importing an existing; save without upload
- Make an observation without a photo; save without upload
- Upload from the toolbar on MyObs
- Offline
- Go into airplane mode
- Make an observation by taking a new photo in the AICamera
- Make an observation by taking a new photo in the StandardCamera
- Make an observation by importing an existing
- Make an observation without a photo
- Turn off airplane mode
- Upload from the toolbar on MyObs
- Update
- Remove the app from the device
- Go to TestFlight and install the latest build
- Sign in and make sure you have at least one uploaded observation with photo
- Make one observation but keep it saved only, and not uploaded
- Install a "Release" build on top of the TestFlight build
- Upload the previously only saved observation
- Online
- Install a "release" build on an Android device and repeat iOS steps
- Install a "Release" build on an iOS device
- Write release notes based on commits since the last release. Try to keep them brief but emphasize what's new and what's fixed. Just keep them in a text editor; you'll save them at a later step.
- Edit
package.json
and update theversion
per semantic versioning rules: bump the patch version if the only changes were bug fixes, bump minor version if there were new features, and bump the major version if the app was completely re-written or can't import data from previous versions. npm install
to set the version inpackage-lock.json
- Commit changes
bundle exec fastlane tag
to create a tag and bump the build number. You'll be prompted to enter those release notes you wrote. (:wq to save and exit)bundle exec fastlane release
to build and push a release to Githubbundle exec fastlane internal
to distribute the builds to internal test groups in TestFlight and the Play Store- If it's the end of the release cycle,
bundle exec fastlane prod
to prepare an App Store release on App Store Connect. You'll be prompted to write custom release notes that summarize changes since the last App Store release (not since the last build). After this command line call, attach the latest build to the new version in the App Store Connect UI on the web and submit for review with manual release control. Haven't figured out a good way to automate this without submitting to review at the same time, maybe impossible. - Wait at least a day for internal testers to report any blocking problems
bundle exec fastlane beta
to distribute the builds to external test groups in TestFlight and the Play Store- After receiving OK during iteration meeting, make App Store release available
- Start the staged release in App Store Connect
- Mark the Github release as the latest non-pre-release