mirror of
https://github.com/facebook/react-native.git
synced 2026-11-18 20:19:07 +00:00
[react-packager][streamline oss] Move open sourced JS source to react-native-github
This commit is contained in:
commit
efae175a8e
434 files changed
+44658
No files matched your search
@@ -0,0 +1,79 @@
|
||||
---
|
||||
id: getting-started
|
||||
title: Getting Started
|
||||
layout: docs
|
||||
category: Quick Start
|
||||
permalink: docs/getting-started.html
|
||||
next: navigatorios
|
||||
---
|
||||
|
||||
|
||||
Our first React Native implementation is `ReactKit`, targeting iOS. We are also
|
||||
working on an Android implementation which we will release later. `ReactKit`
|
||||
apps are built using the [React JS](https://github.com/facebook/react) framework, and render directly to
|
||||
native UIKit elements using a fully asynchronous architecture. There is no
|
||||
browser and no HTML. We have picked what we think is the best set of features
|
||||
from these and other technologies to build what we hope to become the best
|
||||
product development framework available, with an emphasis on iteration speed,
|
||||
developer delight, continuity of technology, and absolutely beautiful and fast
|
||||
products with no compromises in quality or capability.
|
||||
|
||||
## Requirements
|
||||
|
||||
1. OS X - This repo only contains the iOS implementation right now, and Xcode only runs on Mac.
|
||||
2. New to Xcode? [Download it](https://developer.apple.com/xcode/downloads/) from the Mac App Store.
|
||||
3. [Homebrew](http://brew.sh/) is the recommended way to install node, watchman, and flow.
|
||||
4. New to node or npm? `brew install node`
|
||||
5. We recommend installing [watchman](https://facebook.github.io/watchman/docs/install.html), otherwise you might hit a node file watching bug. `brew install watchman`
|
||||
6. If you want to use [flow](http://www.flowtype.org), `brew install flow`
|
||||
|
||||
## Quick start
|
||||
|
||||
Get up and running with our Movies sample app:
|
||||
|
||||
1. Once you have the repo cloned and met all the requirements above, start the
|
||||
packager that will transform your JS code on-the-fly:
|
||||
|
||||
```
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
2. Open the `Examples/Movies/Movies.xcodeproj` project in Xcode.
|
||||
3. Make sure the target is set to `Movies` and that you have an iOS simulator
|
||||
selected to run the app.
|
||||
4. Build and run the project with the Xcode run button.
|
||||
|
||||
You should now see the Movies app running on your iOS simulator.
|
||||
Congratulations! You've just successfully run your first React Native app.
|
||||
|
||||
Now try editing a JavaScript file and viewing your changes. Let's change the
|
||||
movie search placeholder text:
|
||||
|
||||
1. Open the `Examples/Movies/SearchScreen.js` file in your favorite JavaScript
|
||||
editor.
|
||||
2. Look for the current search placeholder text and change it to "Search for an
|
||||
awesome movie...".
|
||||
3. Hit cmd+R ([twice](http://openradar.appspot.com/19613391)) in your iOS simulator to reload the app and see your change.
|
||||
If you don't immediately see your changes, try restarting your app within Xcode.
|
||||
|
||||
Feel free to browse the Movies sample files and customize various properties to
|
||||
get familiar with the codebase and React Native.
|
||||
|
||||
Also check out the UI Component Explorer for more sample code:
|
||||
`Examples/UIExplorer/UIExplorer.xcodeproj`. **Make sure to close the Movies
|
||||
project first - Xcode will break if you have two projects open that reference
|
||||
the same library.**
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
+ Xcode will break if you have two examples open at the same time.
|
||||
+ If `npm start` fails with log spew like:
|
||||
```
|
||||
2015-02-02 10:56 node[24294] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-21)
|
||||
```
|
||||
then you've hit the node file watching bug - `brew install watchman` should fix the issue.
|
||||
+ Jest testing does not yet work on node versions after 0.10.x.
|
||||
+ You can verify the packager is working by loading the [bundle](http://localhost:8081/Examples/Movies/MoviesApp.includeRequire.runModule.bundle) in your browser and
|
||||
inspecting the contents.
|
||||
|
||||
Please report any other issues you encounter so we can fix them ASAP.
|
||||
@@ -0,0 +1,49 @@
|
||||
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`. It turns out that iOS has a very elegant solution to this: you can add elements as a children to an `<Image>` component. This simplifies the API and solves the use case.
|
||||
|
||||
```javascript
|
||||
return (
|
||||
<Image source={...}>
|
||||
<Text>Inside</Text>
|
||||
</Image>
|
||||
);
|
||||
```
|
||||
|
||||
## Off-thread Decoding
|
||||
|
||||
Image decoding can take more than a frame-worth of time. This is one of the major source of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.
|
||||
|
||||
## Static Assets
|
||||
|
||||
In the course of a project you add and remove images and in many instances, you end up shipping images you are not using anymore in the app. In order to fight this, we need to find a way to know statically which images are being used in the app. To do that, we introduced a marker called `ix`. The only allowed way to refer to an image in the bundle is to literally write `ix('name-of-the-asset')` in the source.
|
||||
|
||||
```javascript
|
||||
var { ix } = React;
|
||||
|
||||
// GOOD
|
||||
<Image source={ix('my-icon')} />
|
||||
|
||||
// BAD
|
||||
var icon = this.props.active ? 'my-icon-active' : 'my-icon-inactive';
|
||||
<Image source={ix(icon)} />
|
||||
|
||||
// GOOD
|
||||
var icon = this.props.active ? ix('my-icon-active') : ix('my-icon-inactive');
|
||||
<Image source={icon} />
|
||||
```
|
||||
|
||||
When your entire codebase respects this convention, you're able to do interesting things like automatically packaging the assets that are being used in your app. Note that in the current form, nothing is enforced, but it will be in the future.
|
||||
|
||||
## Best Camera Roll Image
|
||||
|
||||
iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
One of React Native goal 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](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/URLLoadingSystem/URLLoadingSystem.html). The notable difference from web is the security model: you can read from arbitrary websites on the internet, there isn't no concept of [CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
|
||||
|
||||
```javascript
|
||||
var request = new XMLHttpRequest();
|
||||
request.onreadystatechange = (e) => {
|
||||
if (request.readyState !== 4) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (request.status === 200) {
|
||||
console.log('success', request.responseText);
|
||||
} else {
|
||||
console.warn('error');
|
||||
}
|
||||
};
|
||||
|
||||
request.open('GET', 'https://mywebsite.com/endpoint.php');
|
||||
request.send();
|
||||
```
|
||||
|
||||
Please follow the [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) for a description of the API.
|
||||
|
||||
As a developer, you're probably not going to use XMLHttpRequest directly as its API is very tedious to work with. But the fact that it is implemented and compatible with the browser one gives you the ability to use third-party libraries such as [Parse JS SDK](https://parse.com/docs/js_guide) or [super-agent](https://github.com/visionmedia/superagent) directly from npm.
|
||||
|
||||
## Fetch
|
||||
|
||||
[fetch](https://fetch.spec.whatwg.org/) is a better API being worked on by the standard committee and already available in Chrome. It is available in React Native by default.
|
||||
|
||||
```javascript
|
||||
fetch('https://mywebsite.com/endpoint.php')
|
||||
.then((response) => response.text())
|
||||
.then((responseText) => {
|
||||
console.log(responseText);
|
||||
})
|
||||
.catch((error) => {
|
||||
console.warn(error);
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,34 @@
|
||||
Timers are an important part of an application and React Native implements the [browser timers](https://developer.mozilla.org/en-US/Add-ons/Code_snippets/Timers).
|
||||
|
||||
## Timers
|
||||
|
||||
- setTimeout, clearTimeout
|
||||
- setInterval, clearInterval
|
||||
- setImmediate, clearImmediate
|
||||
- requestAnimationFrame, cancelAnimationFrame
|
||||
|
||||
`requestAnimationFrame(fn)` is the exact equivalent of `setTimeout(fn, 0)`, they are triggered right after the screen has been flushed.
|
||||
|
||||
`setImmediate` is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call `setImmediate` within a `setImmediate` callback, it will be executed right away, it won't yield back to native in between.
|
||||
|
||||
The `Promise` implementation uses `setImmediate` its asynchronicity primitive.
|
||||
|
||||
## TimerMixin
|
||||
|
||||
We found out that the primary cause of fatals in apps created with React Native was due to timers firing after a component was unmounted. To solve this recurring issue, we introduced `TimerMixin`. If you include `TimerMixin`, then you can replace your calls to `setTimeout(fn, 500)` with `this.setTimeout(fn, 500)` (just prepend `this.`) and everything will be properly cleaned up for you when the component unmounts.
|
||||
|
||||
```javascript
|
||||
var { TimerMixin } = React;
|
||||
|
||||
var Component = React.createClass({
|
||||
mixins: [TimerMixin],
|
||||
componentDidMount: function() {
|
||||
this.setTimeout(
|
||||
() => { console.log('I do not leak!'); },
|
||||
500
|
||||
);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
We highly recommend never using bare timers and always using this mixin, it will save you from a lot of hard to track down bugs.
|
||||
Reference in new issue
Block a user