React NativeAccessibility
Native App Accessibility (iOS and Android) #
Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
Making Apps Accessible #
Accessibility properties #
accessible (iOS, Android) #
When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.
On Android, ‘accessible={true}’ property for a react-native View will be translated into native ‘focusable={true}’.
AccessibilityEdit on GitHub
Native App Accessibility (iOS and Android) #
Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
Making Apps Accessible #
Accessibility properties #
accessible (iOS, Android) #
When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.
On Android, ‘accessible={true}’ property for a react-native View will be translated into native ‘focusable={true}’.
In the above example, we can't get accessibility focus separately on 'text one' and 'text two'. Instead we get focus on a parent view with 'accessible' property.
accessibilityLabel (iOS, Android) #
When a view is marked as accessible, it is a good practice to set an accessibilityLabel on the view, so that people who use VoiceOver know what element they have selected. VoiceOver will read this string when a user selects the associated element.
To use, set the accessibilityLabel property to a custom string on your View:
Building React Native from source
You will need to build React Native from source if you want to work on a new feature/bug fix, try out the latest features which are not released yet, or maintain your own fork with patches that cannot be merged to the core.
Prerequisites #
Assuming you have the Android SDK installed, run android to open the Android SDK Manager.
Make sure you have the following installed:
- Android SDK version 23 (compileSdkVersion in
build.gradle) - SDK build tools version 23.0.1 (buildToolsVersion in
build.gradle) - Android Support Repository >= 17 (for Android Support Library)
- Android NDK (download & extraction instructions here)
Point Gradle to your Android SDK: either have $ANDROID_SDK and $ANDROID_NDK defined, or create a local.properties file in the root of your react-native checkout with the following contents:
Building React Native from sourceEdit on GitHub
You will need to build React Native from source if you want to work on a new feature/bug fix, try out the latest features which are not released yet, or maintain your own fork with patches that cannot be merged to the core.
Prerequisites #
Assuming you have the Android SDK installed, run android to open the Android SDK Manager.
Make sure you have the following installed:
- Android SDK version 23 (compileSdkVersion in
build.gradle) - SDK build tools version 23.0.1 (buildToolsVersion in
build.gradle) - Android Support Repository >= 17 (for Android Support Library)
- Android NDK (download & extraction instructions here)
Point Gradle to your Android SDK: either have $ANDROID_SDK and $ANDROID_NDK defined, or create a local.properties file in the root of your react-native checkout with the following contents:
Example:
Building the source #
1. Installing the fork #
First, you need to install react-native from your fork. For example, to install the master branch from the official repo, run the following:
Alternatively, you can clone the repo to your node_modules directory and run npm install inside the cloned repo.
2. Adding gradle dependencies #
Add gradle-download-task as dependency in android/build.gradle:
Android Setup
This guide describes basic steps of the Android development environment setup that are required to run React Native android apps on an android emulator. We don't discuss developer tool configuration such as IDEs here.
Install Git #
On Mac, if you have installed XCode, Git is already installed, otherwise run the following:
brew install gitOn Linux, install Git via your package manager.
On Windows, download and install Git for Windows. During the setup process, choose "Run Git from Windows Command Prompt", which will add Git to your
PATHenvironment variable.
Install the Android SDK (unless you have it) #
- Install the latest JDK
- Install the Android SDK:
- On Mac:
brew install android-sdk - On Linux and Windows: Download from the Android website
- On Mac:
Define the ANDROID_HOME environment variable #
IMPORTANT: Make sure the ANDROID_HOME environment variable points to your existing Android SDK:
On Mac, add this to your
~/.bashrc,~/.bash_profileor whatever your shell uses:# If you installed the SDK via Homebrew, otherwise ~/Library/Android/sdk +Android Setup – React Native | A framework for building native apps using React Android SetupEdit on GitHub
This guide describes basic steps of the Android development environment setup that are required to run React Native android apps on an android emulator. We don't discuss developer tool configuration such as IDEs here.
Install Git #
On Mac, if you have installed XCode, Git is already installed, otherwise run the following:
brew install gitOn Linux, install Git via your package manager.
On Windows, download and install Git for Windows. During the setup process, choose "Run Git from Windows Command Prompt", which will add Git to your
PATHenvironment variable.
Install the Android SDK (unless you have it) #
- Install the latest JDK
- Install the Android SDK:
- On Mac:
brew install android-sdk - On Linux and Windows: Download from the Android website
- On Mac:
Define the ANDROID_HOME environment variable #
IMPORTANT: Make sure the
ANDROID_HOMEenvironment variable points to your existing Android SDK:On Mac, add this to your
~/.bashrc,~/.bash_profileor whatever your shell uses:# If you installed the SDK via Homebrew, otherwise ~/Library/Android/sdk export ANDROID_HOME=/usr/local/opt/android-sdkOn Linux, add this to your
~/.bashrc,~/.bash_profileor whatever your shell uses:export ANDROID_HOME=<path_where_you_unpacked_android_sdk>On Windows, go to
Control Panel->System and Security->System->Change settings->Advanced->Environment variables->New
NOTE: You need to restart the Command Prompt (Windows) / Terminal Emulator (Mac OS X, Linux) to apply the new Environment variables.
Use gradle daemon #
React Native Android use gradle as a build system. We recommend to enable gradle daemon functionality which may result in up to 50% improvement in incremental build times for changes in java code. Learn here how to enable it for your platform.
Configure your SDK #
- Open the Android SDK Manager (on Mac start a new shell and run
android); in the window that appears make sure you check:- Android SDK Build-tools version 23.0.1
- Android 6.0 (API 23)
- Android Support Repository
- Click "Install Packages"
Install Genymotion #
Genymotion is much easier to set up than stock Google emulators. However, it's only free for personal use. If you want to use the stock Google emulator, see below.
- Download and install Genymotion.
- Open Genymotion. It might ask you to install VirtualBox unless you already have it.
- Create a new emulator and start it.
- To bring up the developer menu press ⌘+M
Alternative: Create a stock Google emulator #
- Start a new shell and run
android; in the window that appears make sure you check:- Intel x86 Atom System Image (for Android 5.1.1 - API 22)
- Intel x86 Emulator Accelerator (HAXM installer)
- Click "Install Packages".
- Configure hardware acceleration (HAXM), otherwise the emulator is going to be slow.
- Create an Android Virtual Device (AVD):
- Run
android avdand click on Create...
- With the new AVD selected, click
Start...
- Run
- To bring up the developer menu press F2 (or install Frappé)
Windows Hyper-V Alternative #
The Visual Studio Emulator for Android is a free android emulator that is hardware accelerated via Hyper-V. It doesn't require you to install Visual Studio at all.
To use it with react-native you just have to add a key and value to your registry:
- Open the Run Command (Windows+R)
- Enter
regedit.exe - In the Registry Editor navigate to
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Android SDK Tools - Right Click on
Android SDK Toolsand chooseNew > String Value - Set the name to
Path - Double Click the new
PathKey and set the value toC:\Program Files\Android\sdk. The path value might be different on your machine.
You will also need to run the command
adb reverse tcp:8081 tcp:8081with this emulator.Then restart the emulator and when it runs you can just do
react-native run-androidas usual.Profiling Android UI Performance
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling
com.facebook.adsmanager, which shows up asbook.adsmanagerbecause of silly thread name limits in the kernel.On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread),
mqt_jsandmqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with
Choreographer,traversals, andDispatchUI:
JS Thread #
This is where JS is executed. The thread name will be either
mqt_jsor<...>depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things likeJSCall,Bridge.executeJSCall, etc:
Native Modules Thread #
This is where native module calls (e.g. the
UIManager) are executed. The thread name will be eithermqt_native_modulesor<...>. To identify it in the latter case, look for things likeNativeCall,callJavaModuleMethod, andonBatchComplete:
Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either
RenderThreador<...>. To identify it in the latter case, look for things likeDrawFrameandqueueBuffer:
Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see
RCTEventEmitterbeing called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:
This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in
DrawFramethat crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Profiling Android UI PerformanceEdit on GitHub
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling
com.facebook.adsmanager, which shows up asbook.adsmanagerbecause of silly thread name limits in the kernel.On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread),
mqt_jsandmqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with
Choreographer,traversals, andDispatchUI:JS Thread #
This is where JS is executed. The thread name will be either
mqt_jsor<...>depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things likeJSCall,Bridge.executeJSCall, etc:Native Modules Thread #
This is where native module calls (e.g. the
UIManager) are executed. The thread name will be eithermqt_native_modulesor<...>. To identify it in the latter case, look for things likeNativeCall,callJavaModuleMethod, andonBatchComplete:Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either
RenderThreador<...>. To identify it in the latter case, look for things likeDrawFrameandqueueBuffer:Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see
RCTEventEmitterbeing called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in
DrawFramethat crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Animations
Fluid, meaningful animations are essential to the mobile user experience. Like +
Animations – React Native | A framework for building native apps using React AnimationsEdit on GitHub
Fluid, meaningful animations are essential to the mobile user experience. Like everything in React Native, Animation APIs for React Native are currently under development, but have started to coalesce around two complementary systems:
LayoutAnimationfor animated global layout transactions, andAnimatedfor diff --git a/docs/communication-ios.html b/docs/communication-ios.html index 32b082af725..94dcda3fcbc 100644 --- a/docs/communication-ios.html +++ b/docs/communication-ios.html @@ -1,4 +1,4 @@ -Communication between native and React Native – React Native | A framework for building native apps using React Communication between native and React Native
In Integrating with Existing Apps guide and Native UI Components guide we learn how to embed React Native in a native component and vice versa. When we mix native and React Native components, we'll eventually find a need to communicate between these two worlds. Some ways to achieve that have been already mentioned in other guides. This article summarizes available techniques.
Introduction #
React Native is inspired by React, so the basic idea of the information flow is similar. The flow in React is one-directional. We maintain a hierarchy of components, in which each component depends only on its parent and own internal state. We do this with properties: data is passed from a parent to its children in a top-down manner. If we have an ancestor component that rely on the state of its descendant, the recommended solution would be to pass down a callback that would be used by the descendant to update the ancestor.
The same concept applies to React Native. As long as we are building our application purely within the framework, we can drive our app with properties and callbacks. But, when we mix React Native and native components, we need some special, cross-language mechanisms that would allow us to pass information between them.
Properties #
Properties are the simplest way of cross-component communication. So we need a way to pass properties both from native to React Native, and from React Native to native.
Passing properties from native to React Native #
In order to embed a React Native view in a native component, we use
RCTRootView.RCTRootViewis aUIViewthat holds a React Native app. It also provides an interface between native side and the hosted app.RCTRootViewhas an initializer that allows you to pass arbitrary properties down to the React Native app. TheinitialPropertiesparameter has to be an instance ofNSDictionary. The dictionary is internally converted into a JSON object that the top-level JS component can reference.NSArray *imageList = @[@"http://foo.com/bar1.png", +Communication between native and React Native – React Native | A framework for building native apps using React Communication between native and React NativeEdit on GitHub
In Integrating with Existing Apps guide and Native UI Components guide we learn how to embed React Native in a native component and vice versa. When we mix native and React Native components, we'll eventually find a need to communicate between these two worlds. Some ways to achieve that have been already mentioned in other guides. This article summarizes available techniques.
Introduction #
React Native is inspired by React, so the basic idea of the information flow is similar. The flow in React is one-directional. We maintain a hierarchy of components, in which each component depends only on its parent and own internal state. We do this with properties: data is passed from a parent to its children in a top-down manner. If we have an ancestor component that rely on the state of its descendant, the recommended solution would be to pass down a callback that would be used by the descendant to update the ancestor.
The same concept applies to React Native. As long as we are building our application purely within the framework, we can drive our app with properties and callbacks. But, when we mix React Native and native components, we need some special, cross-language mechanisms that would allow us to pass information between them.
Properties #
Properties are the simplest way of cross-component communication. So we need a way to pass properties both from native to React Native, and from React Native to native.
Passing properties from native to React Native #
In order to embed a React Native view in a native component, we use
RCTRootView.RCTRootViewis aUIViewthat holds a React Native app. It also provides an interface between native side and the hosted app.RCTRootViewhas an initializer that allows you to pass arbitrary properties down to the React Native app. TheinitialPropertiesparameter has to be an instance ofNSDictionary. The dictionary is internally converted into a JSON object that the top-level JS component can reference.NSArray *imageList = @[@"http://foo.com/bar1.png", @"http://foo.com/bar2.png"]; NSDictionary *props = @{@"images" : imageList}; diff --git a/docs/debugging.html b/docs/debugging.html index d0255da95d3..a7e24bb7842 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -1,4 +1,4 @@ -Debugging – React Native | A framework for building native apps using React Debugging
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click). You can also install Frappé, a tool for OS X, which allows you to emulate shaking of devices remotely. You can use⌘ + Shift + Ras a shortcut to trigger a shake from Frappé.
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease. - For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting
Reload(or pressing⌘ + rin the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image toImages.xcassetson iOS or tores/drawablefolder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.Chrome Developer Tools #
To debug the JavaScript code in Chrome, select
Debug in Chromefrom the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.In Chrome, press
⌘ + option + ior selectView→Developer→Developer Toolsto toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse tcp:8081 tcp:8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the
Reactin the developer tools (see facebook/react-devtools for more information).Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On
0.5.0-rcand higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.DebuggingEdit on GitHub
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click). You can also install Frappé, a tool for OS X, which allows you to emulate shaking of devices remotely. You can use⌘ + Shift + Ras a shortcut to trigger a shake from Frappé.
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease. - For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting
Reload(or pressing⌘ + rin the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image toImages.xcassetson iOS or tores/drawablefolder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.Chrome Developer Tools #
To debug the JavaScript code in Chrome, select
Debug in Chromefrom the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.In Chrome, press
⌘ + option + ior selectView→Developer→Developer Toolsto toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse tcp:8081 tcp:8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the
Reactin the developer tools (see facebook/react-devtools for more information).Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On
0.5.0-rcand higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.Direct Manipulation
It is sometimes necessary to make changes directly to a component +
Direct Manipulation – React Native | A framework for building native apps using React Direct ManipulationEdit on GitHub
It is sometimes necessary to make changes directly to a component without using state/props to trigger a re-render of the entire subtree. When using React in the browser for example, you sometimes need to directly modify a DOM node, and the same is true for views in mobile diff --git a/docs/embedded-app-android.html b/docs/embedded-app-android.html index 7d7eaf1ef53..25299e9978b 100644 --- a/docs/embedded-app-android.html +++ b/docs/embedded-app-android.html @@ -1,4 +1,4 @@ -
Integrating with Existing Apps – React Native | A framework for building native apps using React Integrating with Existing Apps
Since React makes no assumptions about the rest of your technology stack, it's easily embeddable within an existing non-React Native app.
Requirements #
- an existing, gradle-based Android app
- Node.js, see Getting Started for setup instructions
Prepare your app #
In your app's
build.gradlefile add the React Native dependency:compile 'com.facebook.react:react-native:0.17.+'You can find the latest version of the react-native library on Maven Central. Next, make sure you have the Internet permission in your
AndroidManifest.xml:<uses-permission android:name="android.permission.INTERNET" />This is only really used in dev mode when reloading JavaScript from the development server, so you can strip this in release builds if you need to.
Add native code #
You need to add some native code in order to start the React Native runtime and get it to render something. To do this, we're going to create an
Activitythat creates aReactRootView, starts a React application inside it and sets it as the main content view.public class MyReactActivity extends Activity implements DefaultHardwareBackBtnHandler { +Integrating with Existing Apps – React Native | A framework for building native apps using React Integrating with Existing AppsEdit on GitHub
Since React makes no assumptions about the rest of your technology stack, it's easily embeddable within an existing non-React Native app.
Requirements #
- an existing, gradle-based Android app
- Node.js, see Getting Started for setup instructions
Prepare your app #
In your app's
build.gradlefile add the React Native dependency:compile 'com.facebook.react:react-native:0.17.+'You can find the latest version of the react-native library on Maven Central. Next, make sure you have the Internet permission in your
AndroidManifest.xml:<uses-permission android:name="android.permission.INTERNET" />This is only really used in dev mode when reloading JavaScript from the development server, so you can strip this in release builds if you need to.
Add native code #
You need to add some native code in order to start the React Native runtime and get it to render something. To do this, we're going to create an
Activitythat creates aReactRootView, starts a React application inside it and sets it as the main content view.public class MyReactActivity extends Activity implements DefaultHardwareBackBtnHandler { private ReactRootView mReactRootView; private ReactInstanceManager mReactInstanceManager; diff --git a/docs/embedded-app-ios.html b/docs/embedded-app-ios.html index 76c7ce5f8e9..4fc50a4a76e 100644 --- a/docs/embedded-app-ios.html +++ b/docs/embedded-app-ios.html @@ -1,4 +1,4 @@ -Integrating with Existing Apps – React Native | A framework for building native apps using React Integrating with Existing Apps
Since React makes no assumptions about the rest of your technology stack – it’s commonly noted as simply the
VinMVC– it’s easily embeddable within an existing non-React Native app. In fact, it integrates with other best practice community tools like CocoaPods.Requirements #
- CocoaPods –
gem install cocoapods - Node.js
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them.
- Install nvm with its setup instructions here. Then run
- Install the
react-nativepackage from npm by running the following command in the root directory of your project:npm install react-native
At this point you should have the React Native package installed under a directory named
node_modulesas a sibling to your.xcodeprojfile.Install React Native Using CocoaPods #
CocoaPods is a package management tool for iOS/Mac development. We need to use it to download React Native. If you haven't installed CocoaPods yet, check out this tutorial.
When you are ready to work with CocoaPods, add the following lines to
Podfile. If you don't have one, then create it under the root directory of your project.# Depending on how your project is organized, your node_modules directory may be +Integrating with Existing Apps – React Native | A framework for building native apps using React Integrating with Existing AppsEdit on GitHub
Since React makes no assumptions about the rest of your technology stack – it’s commonly noted as simply the
VinMVC– it’s easily embeddable within an existing non-React Native app. In fact, it integrates with other best practice community tools like CocoaPods.Requirements #
- CocoaPods –
gem install cocoapods - Node.js
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them.
- Install nvm with its setup instructions here. Then run
- Install the
react-nativepackage from npm by running the following command in the root directory of your project:npm install react-native
At this point you should have the React Native package installed under a directory named
node_modulesas a sibling to your.xcodeprojfile.Install React Native Using CocoaPods #
CocoaPods is a package management tool for iOS/Mac development. We need to use it to download React Native. If you haven't installed CocoaPods yet, check out this tutorial.
When you are ready to work with CocoaPods, add the following lines to
Podfile. If you don't have one, then create it under the root directory of your project.# Depending on how your project is organized, your node_modules directory may be # somewhere else; tell CocoaPods where you've installed react-native from npm pod 'React', :path => './node_modules/react-native', :subspecs => [ 'Core', diff --git a/docs/gesture-responder-system.html b/docs/gesture-responder-system.html index 005ff1ffad4..cc1b35328e6 100644 --- a/docs/gesture-responder-system.html +++ b/docs/gesture-responder-system.html @@ -1,4 +1,4 @@ -Gesture Responder System – React Native | A framework for building native apps using React Gesture Responder System
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in
ResponderEventPlugin.js, which contains further details and documentation.Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract
Touchableimplementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. UseTouchableHighlightanywhere where you would use a button or link on web.Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evtis a synthetic touch event with the following form:nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the root elementpageY- The Y position of the touch, relative to the root elementtarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponderandonMoveShouldSetResponderare called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for*ShouldSetResponderhandlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing
on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have aonStartShouldSetResponderCapturehandler which returns true.View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Gesture Responder SystemEdit on GitHub
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in
ResponderEventPlugin.js, which contains further details and documentation.Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract
Touchableimplementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. UseTouchableHighlightanywhere where you would use a button or link on web.Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evtis a synthetic touch event with the following form:nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the root elementpageY- The Y position of the touch, relative to the root elementtarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponderandonMoveShouldSetResponderare called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for*ShouldSetResponderhandlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing
on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have aonStartShouldSetResponderCapturehandler which returns true.View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Getting Started
Requirements #
- OS X - This guide assumes OS X which is needed for iOS development.
- Homebrew is the recommended way to install Watchman and Flow.
- Install Node.js 4.0 or newer.
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them. - New to npm?
- Install nvm with its setup instructions here. Then run
brew install watchman. We recommend installing watchman, otherwise you might hit a node file watching bug.brew install flow, if you want to use flow.
We recommend periodically running
brew update && brew upgradeto keep your programs up-to-date.iOS Setup #
Xcode 7.0 or higher is required. It can be installed from the App Store.
Android Setup #
To write React Native apps for Android, you will need to install the Android SDK (and an Android emulator if you want to work on your app without having to use a physical device). See Android setup guide for instructions on how to set up your Android environment.
NOTE: There is experimental Windows and Linux support for Android development.
Quick start #
$ npm install -g react-native-cli +Getting Started – React Native | A framework for building native apps using React Getting StartedEdit on GitHub
Requirements #
- OS X - This guide assumes OS X which is needed for iOS development.
- Homebrew is the recommended way to install Watchman and Flow.
- Install Node.js 4.0 or newer.
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them. - New to npm?
- Install nvm with its setup instructions here. Then run
brew install watchman. We recommend installing watchman, otherwise you might hit a node file watching bug.brew install flow, if you want to use flow.
We recommend periodically running
brew update && brew upgradeto keep your programs up-to-date.iOS Setup #
Xcode 7.0 or higher is required. It can be installed from the App Store.
Android Setup #
To write React Native apps for Android, you will need to install the Android SDK (and an Android emulator if you want to work on your app without having to use a physical device). See Android setup guide for instructions on how to set up your Android environment.
NOTE: There is experimental Windows and Linux support for Android development.
Quick start #
$ npm install -g react-native-cli $ react-native init AwesomeProjectTo run the iOS app:
$ cd AwesomeProject- Open
ios/AwesomeProject.xcodeprojand hit run in Xcode. - Open
index.ios.jsin your text editor of choice and edit some lines. - Hit ⌘-R in your iOS simulator to reload the app and see your change!
Note: If you are using an iOS device, see the Running on iOS Device page.
To run the Android app:
$ cd AwesomeProject$ react-native run-android- Open
index.android.jsin your text editor of choice and edit some lines. - Press the menu button (F2 by default, or ⌘-M in Genymotion) and select Reload JS to see your change!
- Run
adb logcat *:S ReactNative:V ReactNativeJS:Vin a terminal to see your app's logs
Note: If you are using an Android device, see the Running on Android Device page.
Congratulations! You've successfully run and modified your first React Native app.
If you run into any issues getting started, see the troubleshooting page.
Adding Android to an existing React Native project #
If you already have a (iOS-only) React Native project and want to add Android support, you need to execute the following commands in your existing project directory:
- Update the
react-nativedependency in yourpackage.jsonfile to the latest version $ npm install$ react-native android
Images
Static Image Resources #
As of 0.14 release, React Native provides a unified way of managing images in your iOS and Android apps. To add a static image to your app, place it somewhere in your source code tree and reference it like this:
<Image source={require('./my-icon.png')} />The image name is resolved the same way JS modules are resolved. In the example above the packager will look for
my-icon.pngin the same folder as the component that requires it. Also if you havemy-icon.ios.pngandmy-icon.android.png, the packager will pick the file depending on the platform you are running on.You can also use
@2x,@3x, etc. suffix in the file name to provide images for different screen densities. For example, if you have the following file structure:. +Images – React Native | A framework for building native apps using React ImagesEdit on GitHub
Static Image Resources #
As of 0.14 release, React Native provides a unified way of managing images in your iOS and Android apps. To add a static image to your app, place it somewhere in your source code tree and reference it like this:
<Image source={require('./my-icon.png')} />The image name is resolved the same way JS modules are resolved. In the example above the packager will look for
my-icon.pngin the same folder as the component that requires it. Also if you havemy-icon.ios.pngandmy-icon.android.png, the packager will pick the file depending on the platform you are running on.You can also use
@2x,@3x, etc. suffix in the file name to provide images for different screen densities. For example, if you have the following file structure:. ├── button.js └── img ├── check@2x.png diff --git a/docs/javascript-environment.html b/docs/javascript-environment.html index eef573a8d43..11ced36bfb8 100644 --- a/docs/javascript-environment.html +++ b/docs/javascript-environment.html @@ -1,4 +1,4 @@ -JavaScript Environment – React Native | A framework for building native apps using React JavaScript Environment
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Block scoping:
let greeting = 'hi'; - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Constants:
const answer = 42; - Destructuring:
var {isActive, style} = this.props; - Modules:
import React, { Component } from 'react-native'; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { } - Async Functions:
async function doStuffAsync() { const foo = await doOtherStuffAsync(); };
JavaScript EnvironmentEdit on GitHub
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Block scoping:
let greeting = 'hi'; - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Constants:
const answer = 42; - Destructuring:
var {isActive, style} = this.props; - Modules:
import React, { Component } from 'react-native'; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { } - Async Functions:
async function doStuffAsync() { const foo = await doOtherStuffAsync(); };
Known Issues
Devtools "React" Tab Does Not Work #
It's currently not possible to use the "React" tab in the devtools to inspect app widgets. This is due to a change in how the application scripts are evaluated in the devtools plugin; they are now run inside a Web Worker, and the plugin is unaware of this and so unable to communicate properly with React Native.
However, you can still use the Console feature of the devtools, and debugging JavaScript with breakpoints works too. To use the console, make sure to select the
⚙debuggerWorker.jsentry in the devtools dropdown that by default is set to<top frame>.Missing Modules and Native Views #
This is an initial release of React Native Android and therefore not all of the views present on iOS are released on Android. We are very much interested in the communities' feedback on the next set of modules and views for Open Source. Not all native views between iOS and Android have a 100% equivalent representation, here it will be necessary to use a counterpart eg using ProgressBar on Android in place of ActivityIndicator on iOS.
Our provisional plan for common views and modules includes:
Views #
Maps +Known Issues – React Native | A framework for building native apps using React Known IssuesEdit on GitHub
Devtools "React" Tab Does Not Work #
It's currently not possible to use the "React" tab in the devtools to inspect app widgets. This is due to a change in how the application scripts are evaluated in the devtools plugin; they are now run inside a Web Worker, and the plugin is unaware of this and so unable to communicate properly with React Native.
However, you can still use the Console feature of the devtools, and debugging JavaScript with breakpoints works too. To use the console, make sure to select the
⚙debuggerWorker.jsentry in the devtools dropdown that by default is set to<top frame>.Missing Modules and Native Views #
This is an initial release of React Native Android and therefore not all of the views present on iOS are released on Android. We are very much interested in the communities' feedback on the next set of modules and views for Open Source. Not all native views between iOS and Android have a 100% equivalent representation, here it will be necessary to use a counterpart eg using ProgressBar on Android in place of ActivityIndicator on iOS.
Our provisional plan for common views and modules includes:
Views #
Maps Modal Spinner (http://developer.android.com/guide/topics/ui/controls/spinner.html) Slider (known as SeekBar)Modules #
App State diff --git a/docs/linking-libraries-ios.html b/docs/linking-libraries-ios.html index 9b874fd92c1..8d121efc834 100644 --- a/docs/linking-libraries-ios.html +++ b/docs/linking-libraries-ios.html @@ -1,4 +1,4 @@ -Linking Libraries – React Native | A framework for building native apps using React Linking Libraries
Not every app uses all the native capabilities, and including the code to support +
Linking Libraries – React Native | A framework for building native apps using React Linking LibrariesEdit on GitHub
Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to make it easy to add these features whenever you need them.
With that in mind we exposed many of these features as independent static libraries.
For most of the libs it will be as simple as dragging two files, sometimes a third step will be necessary, but no more than that.
All the libraries we ship with React Native live on the
Librariesfolder in diff --git a/docs/linux-windows-support.html b/docs/linux-windows-support.html index 61492982659..363b5edf654 100644 --- a/docs/linux-windows-support.html +++ b/docs/linux-windows-support.html @@ -1,4 +1,4 @@ -Linux and Windows Support – React Native | A framework for building native apps using React Linux and Windows Support
NOTE: This guide focuses on Android development. You'll need a Mac to build iOS apps.
As React Native on iOS requires a Mac and most of the engineers at Facebook and contributors use Macs, support for OS X is a top priority. However, we would like to support developers using Linux and Windows too. We believe we'll get the best Linux and Windows support from people using these operating systems on a daily basis.
Therefore, Linux and Windows support for the development environment is an ongoing community responsibility. This can mean filing issues and submitting PRs, and we'll help review and merge them. We are looking forward to your contributions and appreciate your patience.
As of version 0.14 Android development with React native is mostly possible on Linux and Windows. You'll need to install Node.js 4.0 or newer. On Linux we recommend installing watchman, otherwise you might hit a node file watching bug.
What's missing on Windows #
On Windows the packager won't be started automatically when you run
react-native run-android. You can start it manually using:cd MyAwesomeApp +Linux and Windows Support – React Native | A framework for building native apps using React Linux and Windows SupportEdit on GitHub
NOTE: This guide focuses on Android development. You'll need a Mac to build iOS apps.
As React Native on iOS requires a Mac and most of the engineers at Facebook and contributors use Macs, support for OS X is a top priority. However, we would like to support developers using Linux and Windows too. We believe we'll get the best Linux and Windows support from people using these operating systems on a daily basis.
Therefore, Linux and Windows support for the development environment is an ongoing community responsibility. This can mean filing issues and submitting PRs, and we'll help review and merge them. We are looking forward to your contributions and appreciate your patience.
As of version 0.14 Android development with React native is mostly possible on Linux and Windows. You'll need to install Node.js 4.0 or newer. On Linux we recommend installing watchman, otherwise you might hit a node file watching bug.
What's missing on Windows #
On Windows the packager won't be started automatically when you run
react-native run-android. You can start it manually using:cd MyAwesomeApp react-native startIf you hit a
ERROR Watcher took too long to loadon Windows, try increasing the timeout in this file (under your node_modules/react-native).Native UI Components
There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like
ScrollViewandTextInput, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, it's quite easy to wrap up these existing components for seamless integration with your React Native application.Like the native module guide, this too is a more advanced guide that assumes you are somewhat familiar with Android SDK programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing
ImageViewcomponent available in the core React Native library.ImageView example #
For this example we are going to walk through the implementation requirements to allow the use of ImageViews in JavaScript.
Native views are created and manipulated by extending
ViewManageror more commonlySimpleViewManager. ASimpleViewManageris convenient in this case because it applies common properties such as background color, opacity, and Flexbox layout.These subclasses are essentially singletons - only one instance of each is created by the bridge. They vend native views to the
NativeViewHierarchyManager, which delegates back to them to set and update the properties of the views as necessary. TheViewManagersare also typically the delegates for the views, sending events back to JavaScript via the bridge.Vending a view is simple:
- Create the ViewManager subclass.
- Implement the
createViewInstancemethod - Expose view property setters using
@ReactProp(or@ReactPropGroup) annotation - Register the manager in
createViewManagersof the applications package. - Implement the JavaScript module
1. Create the
ViewManagersubclass #In this example we create view manager class
ReactImageManagerthat extendsSimpleViewManagerof typeReactImageView.ReactImageViewis the type of object managed by the manager, this will be the custom native view. Name returned bygetNameis used to reference the native view type from JavaScript.... +Native UI Components – React Native | A framework for building native apps using React Native UI ComponentsEdit on GitHub
There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like
ScrollViewandTextInput, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, it's quite easy to wrap up these existing components for seamless integration with your React Native application.Like the native module guide, this too is a more advanced guide that assumes you are somewhat familiar with Android SDK programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing
ImageViewcomponent available in the core React Native library.ImageView example #
For this example we are going to walk through the implementation requirements to allow the use of ImageViews in JavaScript.
Native views are created and manipulated by extending
ViewManageror more commonlySimpleViewManager. ASimpleViewManageris convenient in this case because it applies common properties such as background color, opacity, and Flexbox layout.These subclasses are essentially singletons - only one instance of each is created by the bridge. They vend native views to the
NativeViewHierarchyManager, which delegates back to them to set and update the properties of the views as necessary. TheViewManagersare also typically the delegates for the views, sending events back to JavaScript via the bridge.Vending a view is simple:
- Create the ViewManager subclass.
- Implement the
createViewInstancemethod - Expose view property setters using
@ReactProp(or@ReactPropGroup) annotation - Register the manager in
createViewManagersof the applications package. - Implement the JavaScript module
1. Create the
ViewManagersubclass #In this example we create view manager class
ReactImageManagerthat extendsSimpleViewManagerof typeReactImageView.ReactImageViewis the type of object managed by the manager, this will be the custom native view. Name returned bygetNameis used to reference the native view type from JavaScript.... public class ReactImageManager extends SimpleViewManager<ReactImageView> { diff --git a/docs/native-components-ios.html b/docs/native-components-ios.html index d81755f90cc..518b7de76da 100644 --- a/docs/native-components-ios.html +++ b/docs/native-components-ios.html @@ -1,4 +1,4 @@ -Native UI Components – React Native | A framework for building native apps using React Native UI Components
There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like
ScrollViewandTextInput, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, it's quite easy to wrap up these existing components for seamless integration with your React Native application.Like the native module guide, this too is a more advanced guide that assumes you are somewhat familiar with iOS programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing
MapViewcomponent available in the core React Native library.iOS MapView example #
Let's say we want to add an interactive Map to our app - might as well use
MKMapView, we just need to make it usable from JavaScript.Native views are created and manipulated by subclasses of
RCTViewManager. These subclasses are similar in function to view controllers, but are essentially singletons - only one instance of each is created by the bridge. They vend native views to theRCTUIManager, which delegates back to them to set and update the properties of the views as necessary. TheRCTViewManagers are also typically the delegates for the views, sending events back to JavaScript via the bridge.Vending a view is simple:
- Create the basic subclass.
- Add the
RCT_EXPORT_MODULE()marker macro. - Implement the
-(UIView *)viewmethod
// RCTMapManager.m +Native UI Components – React Native | A framework for building native apps using React Native UI ComponentsEdit on GitHub
There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like
ScrollViewandTextInput, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, it's quite easy to wrap up these existing components for seamless integration with your React Native application.Like the native module guide, this too is a more advanced guide that assumes you are somewhat familiar with iOS programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing
MapViewcomponent available in the core React Native library.iOS MapView example #
Let's say we want to add an interactive Map to our app - might as well use
MKMapView, we just need to make it usable from JavaScript.Native views are created and manipulated by subclasses of
RCTViewManager. These subclasses are similar in function to view controllers, but are essentially singletons - only one instance of each is created by the bridge. They vend native views to theRCTUIManager, which delegates back to them to set and update the properties of the views as necessary. TheRCTViewManagers are also typically the delegates for the views, sending events back to JavaScript via the bridge.Vending a view is simple:
- Create the basic subclass.
- Add the
RCT_EXPORT_MODULE()marker macro. - Implement the
-(UIView *)viewmethod
// RCTMapManager.m #import <MapKit/MapKit.h> #import "RCTViewManager.h" diff --git a/docs/native-modules-android.html b/docs/native-modules-android.html index df173a8e0d9..37418329eb1 100644 --- a/docs/native-modules-android.html +++ b/docs/native-modules-android.html @@ -1,4 +1,4 @@ -Native Modules – React Native | A framework for building native apps using React Native Modules
Sometimes an app needs access to a platform API that React Native doesn't have a corresponding module for yet. Maybe you want to reuse some existing Java code without having to reimplement it in JavaScript, or write some high performance, multi-threaded code such as for image processing, a database, or any number of advanced extensions.
We designed React Native such that it is possible for you to write real native code and have access to the full power of the platform. This is a more advanced feature and we don't expect it to be part of the usual development process, however it is essential that it exists. If React Native doesn't support a native feature that you need, you should be able to build it yourself.
The Toast Module #
This guide will use the Toast example. Let's say we would like to be able to create a toast message from JavaScript.
We start by creating a native module. A native module is a Java class that usually extends the
ReactContextBaseJavaModuleclass and implements the functionality required by the JavaScript. Our goal here is to be able to writeToastAndroid.show('Awesome', ToastAndroid.SHORT);from JavaScript to display a short toast on the screen.package com.facebook.react.modules.toast; +Native Modules – React Native | A framework for building native apps using React Native ModulesEdit on GitHub
Sometimes an app needs access to a platform API that React Native doesn't have a corresponding module for yet. Maybe you want to reuse some existing Java code without having to reimplement it in JavaScript, or write some high performance, multi-threaded code such as for image processing, a database, or any number of advanced extensions.
We designed React Native such that it is possible for you to write real native code and have access to the full power of the platform. This is a more advanced feature and we don't expect it to be part of the usual development process, however it is essential that it exists. If React Native doesn't support a native feature that you need, you should be able to build it yourself.
The Toast Module #
This guide will use the Toast example. Let's say we would like to be able to create a toast message from JavaScript.
We start by creating a native module. A native module is a Java class that usually extends the
ReactContextBaseJavaModuleclass and implements the functionality required by the JavaScript. Our goal here is to be able to writeToastAndroid.show('Awesome', ToastAndroid.SHORT);from JavaScript to display a short toast on the screen.package com.facebook.react.modules.toast; import android.widget.Toast; diff --git a/docs/native-modules-ios.html b/docs/native-modules-ios.html index 415d834ab82..fcf48dafda5 100644 --- a/docs/native-modules-ios.html +++ b/docs/native-modules-ios.html @@ -1,4 +1,4 @@ -Native Modules – React Native | A framework for building native apps using React Native Modules
Sometimes an app needs access to platform API, and React Native doesn't have a corresponding module yet. Maybe you want to reuse some existing Objective-C, Swift or C++ code without having to reimplement it in JavaScript, or write some high performance, multi-threaded code such as for image processing, a database, or any number of advanced extensions.
We designed React Native such that it is possible for you to write real native code and have access to the full power of the platform. This is a more advanced feature and we don't expect it to be part of the usual development process, however it is essential that it exists. If React Native doesn't support a native feature that you need, you should be able to build it yourself.
This is a more advanced guide that shows how to build a native module. It assumes the reader knows Objective-C or Swift and core libraries (Foundation, UIKit).
iOS Calendar Module Example #
This guide will use the iOS Calendar API example. Let's say we would like to be able to access the iOS calendar from JavaScript.
A native module is just an Objective-C class that implements the
RCTBridgeModuleprotocol. If you are wondering, RCT is an abbreviation of ReaCT.// CalendarManager.h +Native Modules – React Native | A framework for building native apps using React Native ModulesEdit on GitHub
Sometimes an app needs access to platform API, and React Native doesn't have a corresponding module yet. Maybe you want to reuse some existing Objective-C, Swift or C++ code without having to reimplement it in JavaScript, or write some high performance, multi-threaded code such as for image processing, a database, or any number of advanced extensions.
We designed React Native such that it is possible for you to write real native code and have access to the full power of the platform. This is a more advanced feature and we don't expect it to be part of the usual development process, however it is essential that it exists. If React Native doesn't support a native feature that you need, you should be able to build it yourself.
This is a more advanced guide that shows how to build a native module. It assumes the reader knows Objective-C or Swift and core libraries (Foundation, UIKit).
iOS Calendar Module Example #
This guide will use the iOS Calendar API example. Let's say we would like to be able to access the iOS calendar from JavaScript.
A native module is just an Objective-C class that implements the
RCTBridgeModuleprotocol. If you are wondering, RCT is an abbreviation of ReaCT.// CalendarManager.h #import "RCTBridgeModule.h" @interface CalendarManager : NSObject <RCTBridgeModule> diff --git a/docs/navigator-comparison.html b/docs/navigator-comparison.html index b675814fe0a..e1229f423e4 100644 --- a/docs/navigator-comparison.html +++ b/docs/navigator-comparison.html @@ -1,4 +1,4 @@ -Navigator Comparison – React Native | A framework for building native apps using React Navigator Comparison
The differences between Navigator +
Navigator Comparison – React Native | A framework for building native apps using React Navigator ComparisonEdit on GitHub
The differences between Navigator and NavigatorIOS are a common source of confusion for newcomers.
Both
NavigatorandNavigatorIOSare components that allow you to manage the navigation in your app between various "scenes" (another word diff --git a/docs/network.html b/docs/network.html index 433c46cef64..b5bf65a37ea 100644 --- a/docs/network.html +++ b/docs/network.html @@ -1,4 +1,4 @@ -Network – React Native | A framework for building native apps using React Network
One of React Native's goals is to be a playground where we can experiment with different architectures and crazy ideas. Since browsers are not flexible enough, we had no choice but to reimplement the entire stack. In the places that we did not intend to change anything, we tried to be as faithful as possible to the browser APIs. The networking stack is a great example.
Fetch #
fetch is a better networking API being worked on by the standards committee and is already available in Chrome. It is available in React Native by default.
Usage #
fetch('https://mywebsite.com/endpoint/')Include a request object as the optional second argument to customize the HTTP request:
fetch('https://mywebsite.com/endpoint/', { +Network – React Native | A framework for building native apps using React NetworkEdit on GitHub
One of React Native's goals is to be a playground where we can experiment with different architectures and crazy ideas. Since browsers are not flexible enough, we had no choice but to reimplement the entire stack. In the places that we did not intend to change anything, we tried to be as faithful as possible to the browser APIs. The networking stack is a great example.
Fetch #
fetch is a better networking API being worked on by the standards committee and is already available in Chrome. It is available in React Native by default.
Usage #
fetch('https://mywebsite.com/endpoint/')Include a request object as the optional second argument to customize the HTTP request:
fetch('https://mywebsite.com/endpoint/', { method: 'POST', headers: { 'Accept': 'application/json', diff --git a/docs/performance.html b/docs/performance.html index 11ac21bb087..bb3b3f0f337 100644 --- a/docs/performance.html +++ b/docs/performance.html @@ -1,4 +1,4 @@ -Performance – React Native | A framework for building native apps using React Performance
A compelling reason for using React Native instead of WebView-based +
Performance – React Native | A framework for building native apps using React PerformanceEdit on GitHub
A compelling reason for using React Native instead of WebView-based tools is to achieve 60 FPS and a native look & feel to your apps. Where possible, we would like for React Native to do the right thing and help you to focus on your app instead of performance optimization, but there diff --git a/docs/platform-specific-code.html b/docs/platform-specific-code.html index 2ab004a119e..d7548b3ae75 100644 --- a/docs/platform-specific-code.html +++ b/docs/platform-specific-code.html @@ -1,4 +1,4 @@ -
Platform Specific Code – React Native | A framework for building native apps using React Platform Specific Code
When building a cross-platform app, the need to write different code for different platforms may arise. This can always be achieved by organizing the various components in different folders:
/common/components/ +Platform Specific Code – React Native | A framework for building native apps using React Platform Specific CodeEdit on GitHub
When building a cross-platform app, the need to write different code for different platforms may arise. This can always be achieved by organizing the various components in different folders:
/common/components/ /android/components/ /ios/components/Another option may be naming the components differently depending on the platform they are going to be used in:
BigButtonIOS.js BigButtonAndroid.jsBut React Native provides two alternatives to easily organize your code separating it by platform:
Platform specific extensions #
React Native will detect when a file has a
.ios.or.android.extension and load the right file for each platform when requiring them from other components.For example, you can have these files in your project:
BigButton.ios.js diff --git a/docs/running-on-device-android.html b/docs/running-on-device-android.html index be6a7f822b6..b8b2ec7d9eb 100644 --- a/docs/running-on-device-android.html +++ b/docs/running-on-device-android.html @@ -1,4 +1,4 @@ -Running On Device – React Native | A framework for building native apps using React Running On Device
Prerequisite: USB Debugging #
You'll need this in order to install your app on your device. First, make sure you have USB debugging enabled on your device.
Check that your device has been successfully connected by running
adb devices:$ adb devices +Running On Device – React Native | A framework for building native apps using React Running On DeviceEdit on GitHub
Prerequisite: USB Debugging #
You'll need this in order to install your app on your device. First, make sure you have USB debugging enabled on your device.
Check that your device has been successfully connected by running
adb devices:$ adb devices List of devices attached emulator-5554 offline # Google emulator 14ed2fcc device # Physical deviceSeeing device in the right column means the device is connected. Android - go figure :) You must have only one device connected.
Now you can use
react-native run-androidto install and launch your app on the device.Accessing development server from device #
You can also iterate quickly on device using the development server. Follow one of the steps described below to make your development server running on your laptop accessible for your device.
Hint
Most modern android devices don't have a hardware menu button, which we use to trigger the developer menu. In that case you can shake the device to open the dev menu (to reload, debug, etc.). Alternatively, you can run the command
adb shell input keyevent 82to open the dev menu (82 being the Menu key code).Using adb reverse #
Note that this option is available on devices running android 5.0+ (API 21).
Have your device connected via USB with debugging enabled (see paragraph above on how to enable USB debugging on your device).
- Run
adb reverse tcp:8081 tcp:8081 - You can use
Reload JSand other development options with no extra configuration
Configure your app to connect to the local dev server via Wi-Fi #
- Make sure your laptop and your phone are on the same Wi-Fi network.
- Open your React Native app on your device. You can do this the same way you'd open any other app.
- You'll see a red screen with an error. This is OK. The following steps will fix that.
- Open the Developer menu by shaking the device or running
adb shell input keyevent 82from the command line. - Go to
Dev Settings. - Go to
Debug server host for device. - Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081). On Mac, you can find the IP address in System Preferences / Network. On Windows, open the command prompt and type
ipconfigto find your machine's IP address (more info). - Go back to the Developer menu and select
Reload JS.
Running On Device
Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.
Accessing development server from device #
You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Change the IP in the URL from
localhostto your laptop's IP. On Mac, you can find the IP address in System Preferences / Network. - In Xcode select your phone as build target and press "Build and run"
Hint
Shake the device to open development menu (reload, debug, etc.)
Using offline bundle #
You can also pack all the JavaScript code within the app itself. This way you can test it without development server running and submit the app to the AppStore.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Follow the instructions for "OPTION 2":
- Uncomment
jsCodeLocation = [[NSBundle mainBundle] ... - Run the
react-native bundle --platform ios --dev false --entry-file index.ios.js --bundle-output iOS/main.jsbundlecommand in terminal from the root directory of your app
- Uncomment
The bundle script supports a couple of flags:
--dev- a boolean with a default value oftrue. With the--dev trueflag, the bundled JavaScript code turns on useful development warnings and limits performance optimizations. For production it is recommended to pass--dev false. Also for production, be sure to have your native build configuration set toRelease(e.g., Xcode's Release configuration for iOS and gradle'sassembleReleasetask for Android) in order to disable things like the shake-to-show developer menu.--minify- pipe the JS code through UglifyJS.
Note that on 0.14 we'll change the API of
react-native bundle. The major changes are:- API is now
entry-file <path>based instead of url based. - Need to specify which platform you're bundling for
--platform <ios|android>. - Option
--outhas been renamed for--bundle-output. - Source maps are no longer automatically generated. Need to specify
--sourcemap-output <path>
Disabling in-app developer menu #
When building your app for production, your app's scheme should be set to
Releaseas detailed in the debugging documentation in order to disable the in-app developer menu.Troubleshooting #
If
curlcommand fails make sure the packager is running. Also try adding--ipv4flag to the end of it.If you started your project a while ago,
main.jsbundlemight not be included into Xcode project. To add it, right click on your project directory and click "Add Files to ..." - choose themain.jsbundlefile that you generated.Running On DeviceEdit on GitHub
Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.
Accessing development server from device #
You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Change the IP in the URL from
localhostto your laptop's IP. On Mac, you can find the IP address in System Preferences / Network. - In Xcode select your phone as build target and press "Build and run"
Hint
Shake the device to open development menu (reload, debug, etc.)
Using offline bundle #
You can also pack all the JavaScript code within the app itself. This way you can test it without development server running and submit the app to the AppStore.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Follow the instructions for "OPTION 2":
- Uncomment
jsCodeLocation = [[NSBundle mainBundle] ... - Run the
react-native bundle --platform ios --dev false --entry-file index.ios.js --bundle-output iOS/main.jsbundlecommand in terminal from the root directory of your app
- Uncomment
The bundle script supports a couple of flags:
--dev- a boolean with a default value oftrue. With the--dev trueflag, the bundled JavaScript code turns on useful development warnings and limits performance optimizations. For production it is recommended to pass--dev false. Also for production, be sure to have your native build configuration set toRelease(e.g., Xcode's Release configuration for iOS and gradle'sassembleReleasetask for Android) in order to disable things like the shake-to-show developer menu.--minify- pipe the JS code through UglifyJS.
Note that on 0.14 we'll change the API of
react-native bundle. The major changes are:- API is now
entry-file <path>based instead of url based. - Need to specify which platform you're bundling for
--platform <ios|android>. - Option
--outhas been renamed for--bundle-output. - Source maps are no longer automatically generated. Need to specify
--sourcemap-output <path>
Disabling in-app developer menu #
When building your app for production, your app's scheme should be set to
Releaseas detailed in the debugging documentation in order to disable the in-app developer menu.Troubleshooting #
If
curlcommand fails make sure the packager is running. Also try adding--ipv4flag to the end of it.If you started your project a while ago,
main.jsbundlemight not be included into Xcode project. To add it, right click on your project directory and click "Add Files to ..." - choose themain.jsbundlefile that you generated.Generating Signed APK
To distribute your Android application via Google Play store, you'll need to generate a signed release APK. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to packaging the JavaScript bundle.
Generating a signing key #
You can generate a private signing key using
keytool.$ keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000This command prompts you for passwords for the keystore and key, and to provide the Distinguished Name fields for your key. It then generates the keystore as a file called
my-release-key.keystore.The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.
Note: Remember to keep your keystore file private and never commit it to version control.
Setting up gradle variables #
- Place the
my-release-key.keystorefile under theandroid/appdirectory in your project folder. - Edit the file
~/.gradle/gradle.propertiesand add the following (replace*****with the correct keystore password, alias and key password),
MYAPP_RELEASE_STORE_FILE=my-release-key.keystore +Generating Signed APK – React Native | A framework for building native apps using React Generating Signed APKEdit on GitHub
To distribute your Android application via Google Play store, you'll need to generate a signed release APK. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to packaging the JavaScript bundle.
Generating a signing key #
You can generate a private signing key using
keytool.$ keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000This command prompts you for passwords for the keystore and key, and to provide the Distinguished Name fields for your key. It then generates the keystore as a file called
my-release-key.keystore.The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.
Note: Remember to keep your keystore file private and never commit it to version control.
Setting up gradle variables #
- Place the
my-release-key.keystorefile under theandroid/appdirectory in your project folder. - Edit the file
~/.gradle/gradle.propertiesand add the following (replace*****with the correct keystore password, alias and key password),
MYAPP_RELEASE_STORE_FILE=my-release-key.keystore MYAPP_RELEASE_KEY_ALIAS=my-key-alias MYAPP_RELEASE_STORE_PASSWORD=***** MYAPP_RELEASE_KEY_PASSWORD=*****These are going to be global gradle variables, which we can later use in our gradle config to sign our app.
Note: Once you publish the app on the Play Store, you will need to republish your app under a different package name (loosing all downloads and ratings) if you want to change the signing key at any point. So backup your keystore and don't forget the passwords.
Adding signing config to your app's gradle config #
Edit the file
android/app/build.gradlein your project folder and add the signing config,... diff --git a/docs/style.html b/docs/style.html index a3b2a6ee273..e8d991eeebf 100644 --- a/docs/style.html +++ b/docs/style.html @@ -1,4 +1,4 @@ -Style – React Native | A framework for building native apps using React Style
React Native doesn't implement CSS but instead relies on JavaScript to let you style your application. This has been a controversial decision and you can read through those slides for the rationale behind it.
+Style – React Native | A framework for building native apps using React StyleEdit on GitHub
React Native doesn't implement CSS but instead relies on JavaScript to let you style your application. This has been a controversial decision and you can read through those slides for the rationale behind it.
Declare Styles #
The way to declare styles in React Native is the following:
var styles = StyleSheet.create({ base: { diff --git a/docs/testing.html b/docs/testing.html index f8cc8f9033f..66d876d0c02 100644 --- a/docs/testing.html +++ b/docs/testing.html @@ -1,4 +1,4 @@ -Testing – React Native | A framework for building native apps using React Testing
Running Tests and Contributing #
The React Native repo has several tests you can run to verify you haven't caused a regression with your PR. These tests are run with the Travis continuous integration system, and will automatically post the results to your PR.
We don't have perfect test coverage of course, especially for complex end-to-end interactions with the user, so many changes will still require significant manual verification, but we would love it if you want to help us increase our test coverage and add more tests and test cases!
Jest Tests #
Jest tests are JS-only tests run on the command line with node. The tests themselves live in the
__tests__directories of the files they test, and there is a large emphasis on aggressively mocking out functionality that is not under test for failure isolation and maximum speed. You can run the existing React Native jest tests withnpm testfrom the react-native root, and we encourage you to add your own tests for any components you want to contribute to. See
getImageSource-test.jsfor a basic example.Note: In order to run your own tests, you will have to first follow the Getting Started instructions on the Jest page and then include the
jestobjects below inpackage.jsonso that the scripts are pre-processed before execution.... +Testing – React Native | A framework for building native apps using React TestingEdit on GitHub
Running Tests and Contributing #
The React Native repo has several tests you can run to verify you haven't caused a regression with your PR. These tests are run with the Travis continuous integration system, and will automatically post the results to your PR.
We don't have perfect test coverage of course, especially for complex end-to-end interactions with the user, so many changes will still require significant manual verification, but we would love it if you want to help us increase our test coverage and add more tests and test cases!
Jest Tests #
Jest tests are JS-only tests run on the command line with node. The tests themselves live in the
__tests__directories of the files they test, and there is a large emphasis on aggressively mocking out functionality that is not under test for failure isolation and maximum speed. You can run the existing React Native jest tests withnpm testfrom the react-native root, and we encourage you to add your own tests for any components you want to contribute to. See
getImageSource-test.jsfor a basic example.Note: In order to run your own tests, you will have to first follow the Getting Started instructions on the Jest page and then include the
jestobjects below inpackage.jsonso that the scripts are pre-processed before execution.... "scripts": { ... "test": "jest" diff --git a/docs/timers.html b/docs/timers.html index a44d6f6b67d..2180f06d6f0 100644 --- a/docs/timers.html +++ b/docs/timers.html @@ -1,4 +1,4 @@ -Timers – React Native | A framework for building native apps using React Timers
Timers are an important part of an application and React Native implements the browser timers.
Timers #
- setTimeout, clearTimeout
- setInterval, clearInterval
- setImmediate, clearImmediate
- requestAnimationFrame, cancelAnimationFrame
requestAnimationFrame(fn)is not the same assetTimeout(fn, 0)- the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).setImmediateis executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you callsetImmediatewithin asetImmediatecallback, it will be executed right away, it won't yield back to native in between.The
Promiseimplementation usessetImmediateas its asynchronicity primitive.InteractionManager #
One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use
InteractionManagerto make sure long-running work is scheduled to start after any interactions/animations have completed.Applications can schedule tasks to run after interactions with the following:
InteractionManager.runAfterInteractions(() => { +Timers – React Native | A framework for building native apps using React TimersEdit on GitHub
Timers are an important part of an application and React Native implements the browser timers.
Timers #
- setTimeout, clearTimeout
- setInterval, clearInterval
- setImmediate, clearImmediate
- requestAnimationFrame, cancelAnimationFrame
requestAnimationFrame(fn)is not the same assetTimeout(fn, 0)- the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).setImmediateis executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you callsetImmediatewithin asetImmediatecallback, it will be executed right away, it won't yield back to native in between.The
Promiseimplementation usessetImmediateas its asynchronicity primitive.InteractionManager #
One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use
InteractionManagerto make sure long-running work is scheduled to start after any interactions/animations have completed.Applications can schedule tasks to run after interactions with the following:
InteractionManager.runAfterInteractions(() => { // ...long-running synchronous task... });Compare this to other scheduling alternatives:
- requestAnimationFrame(): for code that animates a view over time.
- setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
- runAfterInteractions(): run code later, without delaying active animations.
The touch handling system considers one or more active touches to be an 'interaction' and will delay
runAfterInteractions()callbacks until all touches have ended or been cancelled.InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:
var handle = InteractionManager.createInteractionHandle(); // run animation... (`runAfterInteractions` tasks are queued) diff --git a/docs/troubleshooting.html b/docs/troubleshooting.html index dfa6e6a9ef0..ee871232145 100644 --- a/docs/troubleshooting.html +++ b/docs/troubleshooting.html @@ -1,4 +1,4 @@ -Troubleshooting – React Native | A framework for building native apps using React Troubleshooting
Cmd-R does not reload the simulator #
Enable iOS simulator's "Connect hardware keyboard" from menu Hardware > Keyboard menu.
If you are using a non-QWERTY/AZERTY keyboard layout you can use the
Hardware > Shake Gestureto bring up the dev menu and click "Refresh"Port already in use red-screen #
Something is probably already running on port 8081. You can either kill it or try to change which port the packager is listening to.
Kill process on port 8081 #
$ sudo lsof -n -i4TCP:8081 | grep LISTENthen
$ kill -9 <cma process id>Change the port in Xcode #
Edit
AppDelegate.mto use a different port.// OPTION 1 +Troubleshooting – React Native | A framework for building native apps using React TroubleshootingEdit on GitHub
Cmd-R does not reload the simulator #
Enable iOS simulator's "Connect hardware keyboard" from menu Hardware > Keyboard menu.
If you are using a non-QWERTY/AZERTY keyboard layout you can use the
Hardware > Shake Gestureto bring up the dev menu and click "Refresh"Port already in use red-screen #
Something is probably already running on port 8081. You can either kill it or try to change which port the packager is listening to.
Kill process on port 8081 #
$ sudo lsof -n -i4TCP:8081 | grep LISTENthen
$ kill -9 <cma process id>Change the port in Xcode #
Edit
AppDelegate.mto use a different port.// OPTION 1 // Load from development server. Start the server from the repository root: // // $ npm start diff --git a/docs/tutorial.html b/docs/tutorial.html index 177eff8df28..96a6106fa55 100644 --- a/docs/tutorial.html +++ b/docs/tutorial.html @@ -1,4 +1,4 @@ -Tutorial – React Native | A framework for building native apps using React