Edit on GitHubDescription #
Displaying images is a fascinating subject; React Native uses some cool tricks to make it a better experience.
No Automatic Sizing #
If you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.
In React Native, this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or just aspect ratio) of the image in advance, but we believe that it leads to a better user experience.
Background Image via Nesting #
A common feature request from developers familiar with the web is background-image. To handle this use case, simply create a normal <Image> component and add whatever children to it you would like to layer on top of it.
React NativeNative Modules (iOS)
Sometimes an app needs access to platform API, and React Native doesn't have a corresponding wrapper yet. Maybe you want to reuse some existing Objective-C or C++ code without having to reimplement it in JavaScript. Or write some high performance, multi-threaded code such as image processing, network stack, database or rendering.
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 (Swift is not supported yet) and core libraries (Foundation, UIKit).
iOS Calendar module example #
This guide will use iOS Calendar API example. Let's say we would like to be able to access iOS calendar from JavaScript.
Native module is just an Objectve-C class that implements RCTBridgeModule protocol. If you are wondering, RCT is a shorthand for ReaCT.
Native Modules (iOS)
Sometimes an app needs access to platform API, and React Native doesn't have a corresponding wrapper yet. Maybe you want to reuse some existing Objective-C or C++ code without having to reimplement it in JavaScript. Or write some high performance, multi-threaded code such as image processing, network stack, database or rendering.
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 (Swift is not supported yet) and core libraries (Foundation, UIKit).
iOS Calendar module example #
This guide will use iOS Calendar API example. Let's say we would like to be able to access the iOS calendar from JavaScript.
Native module is just an Objectve-C class that implements RCTBridgeModule protocol. If you are wondering, RCT is a shorthand for ReaCT.
Now from your JavaScript file you can call the method like this:
Notice that the exported method name was generated from first part of Objective-C selector. Sometimes it results in a non-idiomatic JavaScript name (like the one in our example). You can change the name by supplying an optional argument to RCT_EXPORT, e.g. RCT_EXPORT(addEvent).
The return type of the method should always be void. React Native bridge is asynchronous, so the only way to pass result to JavaScript is by using callbacks or emitting events (see below).
Argument types #
React Native supports several types of arguments that can be passed from JavaScript code to native module:
- string (
NSString) - number (
NSInteger,float,double,CGFloat,NSNumber) - boolean (
BOOL,NSNumber) - array (
NSArray) of any types from this list - map (
NSDictionary) with string keys and values of any type from this list - function (
RCTResponseSenderBlock)
In our CalendarManager example, if we want to pass event date to native, we have to convert it to a string or a number:
Notice that the exported method name was generated from first part of Objective-C selector. Sometimes it results in a non-idiomatic JavaScript name (like the one in our example). You can change the name by supplying an optional argument to RCT_EXPORT, e.g. RCT_EXPORT(addEvent).
The return type of the method should always be void. React Native bridge is asynchronous, so the only way to pass a result to JavaScript is by using callbacks or emitting events (see below).
Argument types #
React Native supports several types of arguments that can be passed from JavaScript code to native module:
- string (
NSString) - number (
NSInteger,float,double,CGFloat,NSNumber) - boolean (
BOOL,NSNumber) - array (
NSArray) of any types from this list - map (
NSDictionary) with string keys and values of any type from this list - function (
RCTResponseSenderBlock)
In our CalendarManager example, if we want to pass event date to native, we have to convert it to a string or a number:
NOTE: About array and map
React Native doesn't provide any guarantees about the types of values in these structures. Your native module might expect an array of strings, but if JavaScript calls your method with an array containing numbers and strings, you'll get
NSArraywithNSNumberandNSString. It is the developer's responsibility to check array/map value types (seeRCTConvertfor helper methods).
Callbacks #
WARNING
This section is even more experimental than others, we don't have a set of best practices around callbacks yet.
Native module also supports a special kind of argument - callback. In most cases it is used to provide function call result to JavaScript.
NOTE: About array and map
React Native doesn't provide any guarantees about the types of values in these structures. Your native module might expect an array of strings, but if JavaScript calls your method with an array containing numbers and strings, you'll get
NSArraywithNSNumberandNSString. It is the developer's responsibility to check array/map value types (seeRCTConvertfor helper methods).
Callbacks #
WARNING
This section is even more experimental than others, we don't have a set of best practices around callbacks yet.
Native module also supports a special kind of argument- a callback. In most cases it is used to provide the function call result to JavaScript.
RCTResponseSenderBlock accepts only one argument - array of arguments to pass to JavaScript callback. In this case we use node's convention to set first argument to error and the rest - to the result of the function.
RCTResponseSenderBlock accepts only one argument - an array of arguments to pass to the JavaScript callback. In this case we use node's convention to set first argument to error and the rest - to the result of the function.
Native module is supposed to invoke callback only once. It can, however, store the callback as an ivar and invoke it later. This pattern is often used to wrap iOS APIs that require delegate. See RCTAlertManager.
If you want to pass error-like object to JavaScript, use RCTMakeError from RCTUtils.h.
Implementing native module #
The native module should not have any assumptions about what thread it is being called on. React Native invokes native modules methods on a separate serial GCD queue, but this is an implementation detail and might change. If the native module needs to call main-thread-only iOS API, it should schedule the operation on the main queue:
Native module is supposed to invoke its callback only once. It can, however, store the callback as an ivar and invoke it later. This pattern is often used to wrap iOS APIs that require delegate. See RCTAlertManager.
If you want to pass error-like object to JavaScript, use RCTMakeError from RCTUtils.h.
Implementing native module #
The native module should not have any assumptions about what thread it is being called on. React Native invokes native modules methods on a separate serial GCD queue, but this is an implementation detail and might change. If the native module needs to call main-thread-only iOS API, it should schedule the operation on the main queue:
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, we tried to be as faithful as possible to the browser APIs. The networking stack is a great example.
XMLHttpRequest #
XMLHttpRequest API is implemented on-top of iOS networking apis. The notable difference from web is the security model: you can read from arbitrary websites on the internet since there is no concept of CORS.
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.
XMLHttpRequest #
XMLHttpRequest API is implemented on-top of iOS networking apis. The notable difference from web is the security model: you can read from arbitrary websites on the internet since there is no concept of CORS.
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. You can also run them locally with cmd+U in the IntegrationTest and UIExplorer apps in Xcode. You can run the jest tests via npm test on the command line. We don't have great test coverage yet, however, so most changes will still require significant manual verification, but we would love it if you want to help us increase our test coverage!
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 with npm test from the react-native root, and we encourage you to add your own tests for any components you want to contribute to. See getImageSource-test.js for a basic example.
Integration Tests. #
React Native provides facilities to make it easier to test integrated components that require both native and JS components to communicate across the bridge. The two main components are RCTTestRunner and RCTTestModule. RCTTestRunner sets up the ReactNative environment and provides facilities to run the tests as XCTestCases in Xcode (runTest:module is the simplest method). RCTTestModule is exported to JS via NativeModules as TestModule. The tests themselves are written in JS, and must call TestModule.markTestCompleted() when they are done, otherwise the test will timeout and fail. Test failures are primarily indicated by throwing an exception. It is also possible to test error conditions with runTest:module:initialProps:expectErrorRegex: or runTest:module:initialProps:expectErrorBlock: which will expect an error to be thrown and verify the error matches the provided criteria. See IntegrationTestHarnessTest.js and IntegrationTestsTests.m for example usage.
Snapshot Tests #
A common type of integration test is the snapshot test. These tests render a component, and verify snapshots of the screen against reference images using TestModule.verifySnapshot(), using the FBSnapshotTestCase library behind the scenes. Reference images are recorded by setting recordMode = YES on the RCTTestRunner, then running the tests. Snapshots will differ slightly between 32 and 64 bit, and various OS versions, so it's recommended that you enforce tests are run with the correct configuration. It's also highly recommended that all network data be mocked out, along with other potentially troublesome dependencies. See SimpleSnapshotTest for a basic example.
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. You can also run them locally with cmd+U in the IntegrationTest and UIExplorer apps in Xcode. You can run the jest tests via npm test on the command line. We don't have great test coverage yet, however, so most changes will still require significant manual verification, but we would love it if you want to help us increase our test coverage!
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 with npm test from the react-native root, and we encourage you to add your own tests for any components you want to contribute to. See getImageSource-test.js for a basic example.
Integration Tests #
React Native provides facilities to make it easier to test integrated components that require both native and JS components to communicate across the bridge. The two main components are RCTTestRunner and RCTTestModule. RCTTestRunner sets up the ReactNative environment and provides facilities to run the tests as XCTestCases in Xcode (runTest:module is the simplest method). RCTTestModule is exported to JS via NativeModules as TestModule. The tests themselves are written in JS, and must call TestModule.markTestCompleted() when they are done, otherwise the test will timeout and fail. Test failures are primarily indicated by throwing an exception. It is also possible to test error conditions with runTest:module:initialProps:expectErrorRegex: or runTest:module:initialProps:expectErrorBlock: which will expect an error to be thrown and verify the error matches the provided criteria. See IntegrationTestHarnessTest.js and IntegrationTestsTests.m for example usage.
Snapshot Tests #
A common type of integration test is the snapshot test. These tests render a component, and verify snapshots of the screen against reference images using TestModule.verifySnapshot(), using the FBSnapshotTestCase library behind the scenes. Reference images are recorded by setting recordMode = YES on the RCTTestRunner, then running the tests. Snapshots will differ slightly between 32 and 64 bit, and various OS versions, so it's recommended that you enforce tests are run with the correct configuration. It's also highly recommended that all network data be mocked out, along with other potentially troublesome dependencies. See SimpleSnapshotTest for a basic example.