Include Create React Native App in Getting Started
Summary: cc hramos Create React Native App was designed to reduce "time to hello world" to 5-10 minutes for React Native apps. This PR would make CRNA the first way to get started that new users encounter. Included also is some text to help advanced users navigate the question of whether to use CRNA or whether to go straight to `react-native init`. It also includes a new banner for the iOS and Android guides, since they do not apply to CRNA users. Changes are only to the website, screenshots below. This branch was created from the last CI-passing master commit this morning, dependencies were freshly installed and these screenshots are from a clean build. [The Getting Started page](https://www.dropbox.com/s/1s7f3wu3oxr6gpo/Screenshot%202017-04-04%2015.12.29.png?dl=0) [The "native builds only" banner](https://www.dropbox.com/s/nyv51xdiibdkn57/Screenshot%202017-04-04%2015.13.25.png?dl=0) [Pages which still apply to CRNApps have no banner](https://www.dropbox.com/s/qgl0h6uzynqkmy2/Screenshot%202017-04-04%2015.14.10.png?dl=0) <details> * [x] Decide how to handle native code & react-native-cli references outside of the `banner: ejected` guides * [x] [Debugging: Accessing Console Logs](https://facebook.github.io/react-native/docs/debugging.html#accessing-console-logs) isn't needed in CRNA (logs are forwarded alongside packager output) * [x] [Debugging: With Stetho](https://facebook.github.io/react-native/docs/debugging.html#debugging-with-stetho-http-facebook-github-io-stetho-on-android) requires native code * [x] [Debugging: Debugging Native Code](https://facebook.github.io/react-native/docs/debugging.html#debugging-native-code) is native-only * [x] [AppRegistry](https://facebook.github.io/react-native/docs/appregistry.html) only applies to ejected apps, since this is generated from code, I don't think we can set `banner: ejected`? * [x] [Linking](https://facebook.github.io/react-native/docs/linking.html) involves changing Android manifests and other native-side things * [x] [PermissionsAndroid](https://facebook.github.io/react-native/docs/permissionsandroid.html) may be flaky in the Expo client, I can't recall (cc jesseruder) * [x] [PushNotificationIOS](https://facebook.github.io/react-native/docs/pushnotificationios.html) won't work inside Expo, as it has to [handle its own push notifs](https://docs.expo.io/versions/v15.0.0/guides/push-notifications.html) * [x] [Geolocation](https://facebook.github.io/react-native/docs/geolocation.html) requires a polyfill that will most likely ship with next week's release, but that won't have any manifest changes necessary * [ ] Figure out a strategy to handle the fact that CRNA will lag stable RN releases by ~1 week * [x] Confirm linking out to CRNA docs is an OK strategy as opposed to moving ejecting, etc. docs in-tree * [ ] Answer questions (I'll add some review comments to call out a few things) </details> Closes https://github.com/facebook/react-native/pull/13303 Differential Revision: D4950661 Pulled By: hramos fbshipit-source-id: 3dd43828f38ca6ede3f2b0683608c56420dc6525
This commit is contained in:
Adam Perry
Facebook Github Bot
parent
cc1bf6c941
commit
0c9b41f2c0
|
|
@ -37,7 +37,20 @@ type GeoOptions = {
|
|||
* As a browser polyfill, this API is available through the `navigator.geolocation`
|
||||
* global - you do not need to `import` it.
|
||||
*
|
||||
* ### iOS
|
||||
* ### Configuration and Permissions
|
||||
*
|
||||
* <div class="banner-crna-ejected">
|
||||
* <h3>Projects with Native Code Only</h3>
|
||||
* <p>
|
||||
* This section only applies to projects made with <code>react-native init</code>
|
||||
* or to those made with Create React Native App which have since ejected. For
|
||||
* more information about ejecting, please see
|
||||
* the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
|
||||
* the Create React Native App repository.
|
||||
* </p>
|
||||
* </div>
|
||||
*
|
||||
* #### iOS
|
||||
* You need to include the `NSLocationWhenInUseUsageDescription` key
|
||||
* in Info.plist to enable geolocation when using the app. Geolocation is
|
||||
* enabled by default when you create a project with `react-native init`.
|
||||
|
|
@ -46,7 +59,7 @@ type GeoOptions = {
|
|||
* 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as
|
||||
* a background mode in the 'Capabilities' tab in Xcode.
|
||||
*
|
||||
* ### Android
|
||||
* #### Android
|
||||
* To request access to location, you need to add the following line to your
|
||||
* app's `AndroidManifest.xml`:
|
||||
*
|
||||
|
|
|
|||
|
|
@ -21,6 +21,17 @@ const LinkingManager = Platform.OS === 'android' ?
|
|||
NativeModules.IntentAndroid : NativeModules.LinkingManager;
|
||||
|
||||
/**
|
||||
* <div class="banner-crna-ejected">
|
||||
* <h3>Projects with Native Code Only</h3>
|
||||
* <p>
|
||||
* This section only applies to projects made with <code>react-native init</code>
|
||||
* or to those made with Create React Native App which have since ejected. For
|
||||
* more information about ejecting, please see
|
||||
* the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
|
||||
* the Create React Native App repository.
|
||||
* </p>
|
||||
* </div>
|
||||
*
|
||||
* `Linking` gives you a general interface to interact with both incoming
|
||||
* and outgoing app links.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -19,8 +19,18 @@ type Rationale = {
|
|||
}
|
||||
|
||||
type PermissionStatus = 'granted' | 'denied' | 'never_ask_again';
|
||||
|
||||
/**
|
||||
* <div class="banner-crna-ejected">
|
||||
* <h3>Project with Native Code Required</h3>
|
||||
* <p>
|
||||
* This API only works in projects made with <code>react-native init</code>
|
||||
* or in those made with Create React Native App which have since ejected. For
|
||||
* more information about ejecting, please see
|
||||
* the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
|
||||
* the Create React Native App repository.
|
||||
* </p>
|
||||
* </div>
|
||||
*
|
||||
* `PermissionsAndroid` provides access to Android M's new permissions model.
|
||||
* Some permissions are granted by default when the application is installed
|
||||
* so long as they appear in `AndroidManifest.xml`. However, "dangerous"
|
||||
|
|
|
|||
|
|
@ -58,11 +58,22 @@ export type PushNotificationEventName = $Enum<{
|
|||
}>;
|
||||
|
||||
/**
|
||||
* <div class="banner-crna-ejected">
|
||||
* <h3>Projects with Native Code Only</h3>
|
||||
* <p>
|
||||
* This section only applies to projects made with <code>react-native init</code>
|
||||
* or to those made with Create React Native App which have since ejected. For
|
||||
* more information about ejecting, please see
|
||||
* the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
|
||||
* the Create React Native App repository.
|
||||
* </p>
|
||||
* </div>
|
||||
*
|
||||
* Handle push notifications for your app, including permission handling and
|
||||
* icon badge number.
|
||||
*
|
||||
* To get up and running, [configure your notifications with Apple](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/AddingCapabilities/AddingCapabilities.html#//apple_ref/doc/uid/TP40012582-CH26-SW6)
|
||||
* and your server-side system. To get an idea, [this is the Parse guide](https://parse.com/tutorials/ios-push-notifications).
|
||||
* and your server-side system.
|
||||
*
|
||||
* [Manually link](docs/linking-libraries-ios.html#manual-linking) the PushNotificationIOS library
|
||||
*
|
||||
|
|
|
|||
|
|
@ -61,6 +61,17 @@ let _frameRateLoggerSceneListener = null;
|
|||
|
||||
|
||||
/**
|
||||
* <div class="banner-crna-ejected">
|
||||
* <h3>Project with Native Code Required</h3>
|
||||
* <p>
|
||||
* This API only works in projects made with <code>react-native init</code>
|
||||
* or in those made with Create React Native App which have since ejected. For
|
||||
* more information about ejecting, please see
|
||||
* the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
|
||||
* the Create React Native App repository.
|
||||
* </p>
|
||||
* </div>
|
||||
*
|
||||
* `AppRegistry` is the JS entry point to running all React Native apps. App
|
||||
* root components should register themselves with
|
||||
* `AppRegistry.registerComponent`, then the native system can load the bundle
|
||||
|
|
|
|||
|
|
@ -57,8 +57,45 @@ In CI/Xcode, YellowBoxes can also be disabled by setting the `IS_TESTING` enviro
|
|||
|
||||
> RedBoxes and YellowBoxes are automatically disabled in release (production) builds.
|
||||
|
||||
## Chrome Developer Tools
|
||||
|
||||
To debug the JavaScript code in Chrome, select "Debug JS Remotely" from the Developer Menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui).
|
||||
|
||||
Select `Tools → Developer Tools` from the Chrome Menu to open the [Developer Tools](https://developer.chrome.com/devtools). You may also access the DevTools using keyboard shortcuts (**`Command`**`⌘` + **`Option`**`⌥` + **`I`** on Mac, **`Ctrl`** + **`Shift`** + **`I`** on Windows). You may also want to enable [Pause On Caught Exceptions](http://stackoverflow.com/questions/2233339/javascript-is-there-a-way-to-get-chrome-to-break-on-all-errors/17324511#17324511) for a better debugging experience.
|
||||
|
||||
> It is [currently not possible](https://github.com/facebook/react-devtools/issues/229) to use the "React" tab in the Chrome Developer Tools to inspect app widgets. You can use Nuclide's "React Native Inspector" as a workaround.
|
||||
|
||||
### Debugging using a custom JavaScript debugger
|
||||
|
||||
To use a custom JavaScript debugger in place of Chrome Developer Tools, set the `REACT_DEBUGGER` environment variable to a command that will start your custom debugger. You can then select "Debug JS Remotely" from the Developer Menu to start debugging.
|
||||
|
||||
The debugger will receive a list of all project roots, separated by a space. For example, if you set `REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative"`, then the command `node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app` will be used to start your debugger.
|
||||
|
||||
> Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
|
||||
|
||||
## Performance Monitor
|
||||
|
||||
You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.
|
||||
|
||||
<hr style="margin-top:25px; margin-bottom:25px;"/>
|
||||
|
||||
# Debugging in Ejected Apps
|
||||
|
||||
<div class="banner-crna-ejected" style="margin-top:25px">
|
||||
<h3>Projects with Native Code Only</h3>
|
||||
<p>
|
||||
The remainder of this guide only applies to projects made with <code>react-native init</code>
|
||||
or to those made with Create React Native App which have since ejected. For
|
||||
more information about ejecting, please see
|
||||
the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
|
||||
the Create React Native App repository.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
## Accessing console logs
|
||||
|
||||
Note: if you're using Create React Native App, these already appear in the same terminal output as the packager.
|
||||
|
||||
You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:
|
||||
|
||||
```
|
||||
|
|
@ -68,15 +105,9 @@ $ react-native log-android
|
|||
|
||||
You may also access these through `Debug → Open System Log...` in the iOS Simulator or by running `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal while an Android app is running on a device or emulator.
|
||||
|
||||
## Chrome Developer Tools
|
||||
## Debugging on a device with Chrome Developer Tools
|
||||
|
||||
To debug the JavaScript code in Chrome, select "Debug JS Remotely" from the Developer Menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui).
|
||||
|
||||
Select `Tools → Developer Tools` from the Chrome Menu to open the [Developer Tools](https://developer.chrome.com/devtools). You may also access the DevTools using keyboard shortcuts (**`Command`**`⌘` + **`Option`**`⌥` + **`I`** on Mac, **`Ctrl`** + **`Shift`** + **`I`** on Windows). You may also want to enable [Pause On Caught Exceptions](http://stackoverflow.com/questions/2233339/javascript-is-there-a-way-to-get-chrome-to-break-on-all-errors/17324511#17324511) for a better debugging experience.
|
||||
|
||||
> It is [currently not possible](https://github.com/facebook/react-devtools/issues/229) to use the "React" tab in the Chrome Developer Tools to inspect app widgets. You can use Nuclide's "React Native Inspector" as a workaround.
|
||||
|
||||
### Debugging on a device with Chrome Developer Tools
|
||||
Note: if you're using Create React Native App, this is configured for you already.
|
||||
|
||||
On iOS devices, open the file [`RCTWebSocketExecutor.m`](https://github.com/facebook/react-native/blob/master/Libraries/WebSocket/RCTWebSocketExecutor.m) and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.
|
||||
|
||||
|
|
@ -88,14 +119,6 @@ Alternatively, select "Dev Settings" from the Developer Menu, then update the "D
|
|||
|
||||
> If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.
|
||||
|
||||
### Debugging using a custom JavaScript debugger
|
||||
|
||||
To use a custom JavaScript debugger in place of Chrome Developer Tools, set the `REACT_DEBUGGER` environment variable to a command that will start your custom debugger. You can then select "Debug JS Remotely" from the Developer Menu to start debugging.
|
||||
|
||||
The debugger will receive a list of all project roots, separated by a space. For example, if you set `REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative"`, then the command `node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app` will be used to start your debugger.
|
||||
|
||||
> Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
|
||||
|
||||
### Debugging with [Stetho](http://facebook.github.io/stetho/) on Android
|
||||
|
||||
1. In ```android/app/build.gradle```, add these lines in the `dependencies` section:
|
||||
|
|
@ -139,7 +162,3 @@ The debugger will receive a list of all project roots, separated by a space. For
|
|||
## Debugging native code
|
||||
|
||||
When working with native code (e.g. when writing native modules) you can launch the app from Android Studio or Xcode and take advantage of the debugging features (setup breakpoints, etc.) as you would in case of building a standard native app.
|
||||
|
||||
## Performance Monitor
|
||||
|
||||
You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.
|
||||
|
|
|
|||
|
|
@ -12,8 +12,40 @@ your system, so that you can build apps with it right away. If you already
|
|||
have React Native installed, you can skip ahead to the
|
||||
[Tutorial](docs/tutorial.html).
|
||||
|
||||
The instructions are a bit different depending on your development operating system, and whether you want to start developing for iOS or Android. If you
|
||||
want to develop for both iOS and Android, that's fine - you just have to pick
|
||||
## Quick Start
|
||||
|
||||
[Create React Native App](https://github.com/react-community/create-react-native-app) is the easiest way to start building a new React Native application. It allows you to start a project without installing or configuring any tools to build native code.
|
||||
|
||||
No Xcode or Android Studio installation is required. Assuming that you have Node installed, you can run the following commands to create a new React Native project called "AwesomeProject":
|
||||
|
||||
```
|
||||
npm install -g create-react-native-app
|
||||
create-react-native-app AwesomeProject
|
||||
cd AwesomeProject
|
||||
npm start
|
||||
```
|
||||
|
||||
This will start a development server for you, and print a QR code in your terminal.
|
||||
|
||||
Install the [Expo](https://expo.io) client app on your iOS or Android phone, make sure your phone is on the same network as your computer, and scan the QR code in your terminal to open your project. Create React Native App also has a [user guide](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md) you can reference if you have questions specific to the tool.
|
||||
|
||||
Once you've created your project and opened it in the Expo client app, you can proceed to the [Tutorial](docs/tutorial.html).
|
||||
|
||||
### Caveats
|
||||
|
||||
Because you don't build any native code with Create React Native App, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.
|
||||
|
||||
If you know that you'll eventually need to include your own native code, Create React Native App is still a good way to get started. In that case you'll just need to "[eject](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md#ejecting-from-create-react-native-app)" eventually to create your own native builds. If you do eject, the native build instructions below will be required to continue working on your project.
|
||||
|
||||
If you're integrating React Native into an existing project, you'll want to skip Create React Native App and go directly to setting up the native build environment. See below for instructions on configuring a native build environment for React Native.
|
||||
|
||||
<hr style="margin-top:25px"/>
|
||||
|
||||
## Building Projects with Native Code
|
||||
|
||||
Follow these instructions if you need to build native code in your project. For example, if you "ejected" from Create React Native app, or if you are integrating React Native into an existing application, you'll need this section.
|
||||
|
||||
The instructions are a bit different depending on your development operating system, and whether you want to start developing for iOS or Android. If you want to develop for both iOS and Android, that's fine - you just have to pick
|
||||
one to start with, since the setup is a bit different.
|
||||
|
||||
<div class="toggler">
|
||||
|
|
@ -312,6 +344,7 @@ If you have a physical Android device, you can use it for development in place o
|
|||
Use the React Native command line interface to generate a new React Native project called "AwesomeProject", then run `react-native run-ios` inside the newly created folder.
|
||||
|
||||
```
|
||||
# skip this first command if you ejected from Create React Native App
|
||||
react-native init AwesomeProject
|
||||
cd AwesomeProject
|
||||
react-native run-ios
|
||||
|
|
@ -328,6 +361,7 @@ You should see your new app running in the iOS Simulator shortly.
|
|||
Use the React Native command line interface to generate a new React Native project called "AwesomeProject", then run `react-native run-android` inside the newly created folder:
|
||||
|
||||
```
|
||||
# skip this first command if you ejected from Create React Native App
|
||||
react-native init AwesomeProject
|
||||
cd AwesomeProject
|
||||
react-native run-android
|
||||
|
|
@ -370,6 +404,7 @@ Congratulations! You've successfully run and modified your first React Native ap
|
|||
Use the React Native command line interface to generate a new React Native project called "AwesomeProject", then run `react-native run-android` inside the newly created folder:
|
||||
|
||||
```
|
||||
# skip this first command if you ejected from Create React Native App
|
||||
react-native init AwesomeProject
|
||||
cd AwesomeProject
|
||||
react-native run-android
|
||||
|
|
@ -382,6 +417,7 @@ react-native run-android
|
|||
Use the React Native command line interface to generate a new React Native project called "AwesomeProject", then run `react-native run-android` inside the newly created folder.
|
||||
|
||||
```
|
||||
# skip this first command if you ejected from Create React Native App
|
||||
react-native init AwesomeProject
|
||||
cd AwesomeProject
|
||||
react-native run-android
|
||||
|
|
|
|||
|
|
@ -28,8 +28,6 @@ The folks who built the app for Facebook's F8 conference in 2016 also [open-sour
|
|||
|
||||
[Nuclide](https://nuclide.io/) is the IDE that Facebook uses internally for React Native development. The killer feature of Nuclide is its debugging ability. It also has great inline Flow support.
|
||||
|
||||
[Create React Native App](https://github.com/react-community/create-react-native-app) makes it significantly easier to get started with a React Native project. There's no need to use Xcode or Android Studio, and you can develop for your iOS device using Linux or Windows.
|
||||
|
||||
[Ignite](https://github.com/infinitered/ignite) is a starter kit that uses Redux and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.
|
||||
|
||||
[CodePush](https://microsoft.github.io/code-push/) is a service from Microsoft that makes it easy to deploy live updates to your React Native app. If you don't like going through the app store process to deploy little tweaks, and you also don't like setting up your own backend, give CodePush a try.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,30 @@
|
|||
/**
|
||||
* Copyright (c) 2015-present, Facebook, Inc.
|
||||
* All rights reserved.
|
||||
*
|
||||
* This source code is licensed under the BSD-style license found in the
|
||||
* LICENSE file in the root directory of this source tree. An additional grant
|
||||
* of patent rights can be found in the PATENTS file in the same directory.
|
||||
*
|
||||
* @providesModule EjectBanner
|
||||
*/
|
||||
'use strict';
|
||||
|
||||
var React = require('React');
|
||||
|
||||
var EjectBanner = React.createClass({
|
||||
render: function() {
|
||||
return (
|
||||
<div className="banner-crna-ejected">
|
||||
<h3>Project with Native Code Required</h3>
|
||||
<p>
|
||||
This page only applies to projects made with <code>react-native init</code> or to those made
|
||||
with Create React Native App which have since ejected. For more information about ejecting,
|
||||
please see the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on the Create React Native App repository.
|
||||
</p>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
module.exports = EjectBanner;
|
||||
|
|
@ -11,6 +11,7 @@
|
|||
'use strict';
|
||||
|
||||
var DocsSidebar = require('DocsSidebar');
|
||||
var EjectBanner = require('EjectBanner');
|
||||
var Footer = require('Footer');
|
||||
var Header = require('Header');
|
||||
var Marked = require('Marked');
|
||||
|
|
@ -44,6 +45,7 @@ var DocsLayout = React.createClass({
|
|||
<div className="inner-content">
|
||||
<a id="content" />
|
||||
<Header level={1}>{metadata.title}</Header>
|
||||
{(metadata.banner === 'ejected') ? <EjectBanner/> : null}
|
||||
<Marked>{content}</Marked>
|
||||
<div className="docs-prevnext">
|
||||
{metadata.previous && <a className="docs-prev" href={'docs/' + metadata.previous + '.html#content'}>← Prev</a>}
|
||||
|
|
|
|||
Loading…
Reference in New Issue