This repo is the current React-Native version of the NewSpring app. It is a react-native/react-native-web port of Holtzman. It's intended to serve as a starting point for the open-source initiative in the larger Apollos project. However, this repo is not necessarilly intended to be forked or directly implemented for other organizations (although you're more then welcome to!). Instead, we plan to rip out the core UI components into a separate UI component library ("apollos-ui"), and also release a (small) set of tooling to facilitate creating an Apollos app. This tooling would likely be based on something like Create React Native App and could contain a boilerplate set up with a turn-key "Church app" ready to go for your customization.
Other relevant projects in the NewSpring ecosystem:
- Heighliner: The current GraphQL implementation that this project connects to. In the future, we forsee releasing a separate "Apollos Data" project to replace Heighliner.
- Holtzman: The existing React / Cordova based NewSpring app. This repo is a direct React-Native / React-Native port of this project.
Apollos is a reactive application framework for building react web + react native applications. It is built using React-Native, Apollo, React Native Web, Create React Native App and Create React App. This repository contains the application framework and instructions for usage.
Browse the interactive documentation, check out the master branch on the web or on your mobile device with Expo:
- Quick Start
- Available Scripts
- Writing and Running Tests
- Environment Variables
- Adding Flow
- Customizing App Display Name and Icon
- Sharing and Deployment
- Troubleshooting
git clone git@github.com:NewSpring/Apollos.git
cd Apollos
yarn install
yarn startRuns Apollos in development mode for native (mobile) devices. Open it in the Expo app on your phone to view it, or press one of the available options in the packager after it starts. It will reload if you save edits to files, and you will see build errors and logs in the terminal.
Sometimes you may need to reset or clear the React Native packager's cache. To do so, you can pass the --reset-cache flag to the start script:
yarn start -- --reset-cache
# or
yarn start -- --reset-cache
Runs eslint and the jest test runner on your tests.
Like yarn start, but builds the app for web. Will also open a web browser.
Like yarn start, but also attempts to open the app in the iOS Simulator if you're on a Mac and have it installed.
Like yarn start, but also attempts to open your app on a connected Android device or emulator. Requires an installation of Android build tools (see React Native docs for detailed setup). We also recommend installing Genymotion as your Android emulator. Once you've finished setting up the native build environment, there are two options for making the right copy of adb available to Create React Native App:
- Make sure that you can run adb from your terminal.
- Open Genymotion and navigate to
Settings -> ADB. Select “Use custom Android SDK tools” and update with your Android SDK directory.
- Find Genymotion’s copy of adb. On macOS for example, this is normally
/Applications/Genymotion.app/Contents/MacOS/tools/. - Add the Genymotion tools directory to your path (instructions for Mac, Linux, and Windows).
- Make sure that you can run adb from your terminal.
This will start the process of "ejecting" from Create React Native App's build scripts. You'll be asked a couple of questions about how you'd like to build your project.
Warning: Running eject is a permanent action (aside from whatever version control system you use). An ejected app will require you to have an Xcode and/or Android Studio environment set up.
This will start the process of "ejecting" from Create React Native App's build scripts. You'll be asked a couple of questions about how you'd like to build your project.
Warning: Running eject is a permanent action (aside from whatever version control system you use). An ejected app will require you to have an Xcode and/or Android Studio environment set up.
Creates a build for the web version of the app.
Like yarn run build, except it creates a build for storybook on web.
Starts the native storybook packager. yarn run storybook-ios or yarn run storybook-android is also required to view storybook on a device (TODO: this experience should be improved).
Starts the storybook web packager.
You can edit app.json to include configuration keys under the expo key.
To change your app's display name, set the expo.name key in app.json to an appropriate string.
To set an app icon, set the expo.icon key in app.json to be either a local path or a URL. It's recommended that you use a 512x512 png file with transparency.
This project is set up to use jest for tests. You can configure whatever testing strategy you like, but jest works out of the box. Create test files in directories called __tests__ or with the .test extension to have the files loaded by jest. See the the template project for an example test. The jest documentation is also a wonderful resource, as is the React Native testing tutorial.
You can configure environment variables by creating a .env file.
TODO: document required env vars.
Create React Native App does a lot of work to make app setup and development simple and straightforward, but it's very difficult to do the same for deploying to Apple's App Store or Google's Play Store without relying on a hosted service.
Expo provides free hosting for apps created by CRNA, allowing you to share your app through the Expo client app. This requires registration for an Expo account.
Install the exp command-line tool, and run the publish command:
$ yarn i -g exp
$ exp publish
You can also use a service like Expo's standalone builds if you want to get an IPA/APK for distribution without having to build the native code yourself.
See the ejecting guide for more details about this option.
If you're unable to load your app on your phone due to a network timeout or a refused connection, a good first step is to verify that your phone and computer are on the same network and that they can reach each other. Create React Native App needs access to ports 19000 and 19001 so ensure that your network and firewall settings allow access from your device to your computer on both of these ports.
Try opening a web browser on your phone and opening the URL that the packager script prints, replacing exp:// with http://. So, for example, if underneath the QR code in your terminal you see:
exp://192.168.0.1:19000
Try opening Safari or Chrome on your phone and loading
http://192.168.0.1:19000
and
http://192.168.0.1:19001
If this works, but you're still unable to load your app by scanning the QR code, please open an issue on the Create React Native App repository with details about these steps and any other error messages you may have received.
If you're not able to load the http URL in your phone's web browser, try using the tethering/mobile hotspot feature on your phone (beware of data usage, though), connecting your computer to that WiFi network, and restarting the packager.
If you're on a Mac, there are a few errors that users sometimes see when attempting to yarn run ios:
- "non-zero exit code: 107"
- "You may need to install Xcode" but it is already installed
- and others
There are a few steps you may want to take to troubleshoot these kinds of errors:
- Make sure Xcode is installed and open it to accept the license agreement if it prompts you. You can install it from the Mac App Store.
- Open Xcode's Preferences, the Locations tab, and make sure that the
Command Line Toolsmenu option is set to something. Sometimes when the CLI tools are first installed by Homebrew this option is left blank, which can prevent Apple utilities from finding the simulator. Make sure to re-runyarn/yarn run iosafter doing so. - If that doesn't work, open the Simulator, and under the app menu select
Reset Contents and Settings.... After that has finished, quit the Simulator, and re-runyarn/yarn run ios.
If you're not able to scan the QR code, make sure your phone's camera is focusing correctly, and also make sure that the contrast on the two colors in your terminal is high enough. For example, WebStorm's default themes may not have enough contrast for terminal QR codes to be scannable with the system barcode scanners that the Expo app uses.
If this causes problems for you, you may want to try changing your terminal's color theme to have more contrast, or running Create React Native App from a different terminal. You can also manually enter the URL printed by the packager script in the Expo app's search bar to load it manually.