Include Create React Native App in Getting Started by anp · Pull Request #13303 · react/react-native

anp · 2017-04-04T22:44:14Z

Motivation

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.

Test Plan

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

The "native builds only" banner

Pages which still apply to CRNApps have no banner

TODO before merging

Details

anp · 2017-04-04T22:44:56Z

-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 native build tools.


This phrasing is meant to mirror Create React App's in the React docs, but is fungible as far as I'm concerned.

anp · 2017-04-04T22:45:20Z

+
+[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 native build tools.
+
+Assuming that you have Node installed, no Xcode or Android Studio installation is required:


Technically CRNA supports Node 6 or higher, not sure it's worth specifying here due to risk of bitrot.

The phrasing here seems a bit odd to me (but keep in mind, English is my second language). The way I read it, Xcode or Android Studio may be required if I don't have Node installed.
Maybe we can split into two sentences, and swap the order? Something like:

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 projected called "AwesomeProject":

I'm mirroring the instructions for Native Builds at the end here, "AwesomeProject" could be anything but ideally it would match the original RN init commands.

After this PR gets merged I'll probably take another pass at updating the Getting Started guide and subsequent pages, as I'd like to update the tutorial so that it builds on top of the CRNA started project similar to what we did at F8 this year.

That's a good point -- writing for ESL audiences is not my strength.

anp · 2017-04-04T22:46:17Z

+
+Once you've created your project and opened it in the Expo client app, you can proceed to the [Tutorial](docs/tutorial.html).
+
+### Caveats


I think having this as a subsection makes sense because we want to surface the information for advanced users (read: the ones who are willing to read more than 3 sentences due to existing investment) early on without muddying the waters for really new people.

Very open to suggestions on the structure of this though.

Ideally we'd have a standalone CRNA doc that covers any caveats, as well as the ejection process. We can tackle that in a different PR though, I'm OK with this section here for now.

I'll make a note to follow up with you on that after you're back.

anp · 2017-04-04T22:47:09Z

+
+### 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.


Technically this includes the Expo SDK as well, but there's a tradeoff here:

don't want to have to educate new users too much about all of these distinctions

users may not use CRNA if they believe that there's not enough in the client to experiment with

I think it's OK to favor the former over the latter, myself.

Looks good to me, once we have a CRNA doc we can be more verbose there.

anp · 2017-04-04T22:47:59Z

+
+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"/>


halp i'm trapped in 1999 and can't get out

brentvatne · 2017-04-05T00:12:20Z

PermissionsAndroid may be flaky in the Expo client, I can't recall (cc @jesseruder)

We should make this delegate to our API maybe @dikaiosune? In the same way we do it for navigator.geolocation

PushNotificationIOS won't work inside Expo, as it has to handle its own push notifs

Does it work at all, CRNA or otherwise? 😆
In all seriousness, this should probably be removed from core.

Geolocation requires a polyfill that will most likely ship with next week's release, but that won't have any manifest changes necessary

Yup! As discussed in Slack, we may want to have some way to generically say/flag "if you use CRNA this works without any additional work, if not, here's a bunch of stuff you need to do".

Linking involves changing Android manifests and other native-side things

Same sort of thing as geolocation would be useful here.

anp · 2017-04-05T01:00:43Z

PermissionsAndroid:

Talking to @jesseruder it sounds likely that a true polyfill here will be brittle, maybe? The way that using the API fails inside Expo isn't great, so we could at a minimum override it to throw a nicer exception + add a docs banner here that links to Expo's permissions docs?

PushNotificationIOS:

I don't contest its removal, but since it's there right now we need to have some answer for its docs :P.

Geolocation:

I agree that we need something to call out do-this-only-if-building-native steps. @hramos what do you think about making some sections collapsable vs. using a banner vs. some other strategy to differentiate?

Linking:

I think we probably need to document the Expo Linking strategy first, right?

peterp · 2017-04-05T09:50:08Z

I personally don't think that this should be the suggested route as Snack and Create React Native App appear to fill an evaluation, learning, or tutorial phase rather than a setting up your own development environment phase.

Perhaps the "Getting Started" is the correct place, but we could use an explicit document for setting up your own development environment?

anp · 2017-04-06T19:16:34Z

@peterp I'll flesh out the motivation of the PR a little more.

I think that React's Installation guide offers a nice example for React Native to follow. There are 3 options there:

CodePen (try it in your browser)
Create React App (boilerplate generator which often just fills the evaluation, learning, or tutorial role)
Full-blown make-your-own-build setup (lots of people don't need this, and if this were the only option it would be a big blocker for new user adoption)

Today, the React Native docs only show react-native-cli, which is kind of a hybrid of 2 & 3 from that list. It does have a template project it creates for you, but you also need to setup a full-blown native mobile dev environment to be able to use it.

Create React Native App fits in more or less as number 2 on that list. You're right that it fills an evaluation, learning, or tutorial role today. However, I think it's extremely important for documentation to provide new users with ways to get familiar before they dive all the way in -- we know from experience reports of new users that a multi-GB Xcode or AS download/install is a huge barrier to trying out React Native, which means they may never get the chance to fall in love with it.

I agree that it could make sense to separate Getting Started from a "Native Builds" document, but I think there are challenges with that approach. For one thing, unless you use Expo's build service, it's difficult today to take CRNA all the way to production the same way you can with Create React App, and we wouldn't want to give new users the impression that they can't build real, deployable, production-grade mobile apps with RN. That's what we all presumably want new users to do! The inability to write your own native code also means that for many users CRNA won't be the only way they ever use React Native, even if they don't publish an app to the stores. As a result of these and other tradeoffs, I think it's important to maintain a front-and-center presence for the Native Build section in addition to showing CRNA first.

The way I'm proposing to structure this is an attempt to honor both goals: acquire new users without hiding the full power of RN. That said, this may not be the correct path forward.

@hramos what do you think?

Looking through the current community Parse tutorials I found several candidates for a replacement: http://docs.parseplatform.org/parse-server/guide/#push-notifications-quick-start https://github.com/parse-community/PushTutorial/blob/master/iOS/README.md#1-creating-the-ssl-certificate The first (as of 4/6/17) is a broken anchor, and the second, which comes from text that I assume the first anchor is meant to point to, is a 404.

This is partially supported in CRNA right now, but it will be a month or two before we can figure out full support for all of the methods.

hramos · 2017-04-06T23:46:11Z

I believe CRNA is a great way for someone completely new to React Native to get started building their first app. With CRNA there is no need to set up a full development environment for both iOS and Android, and as the person maintaining the Getting Started guide for the past year or so -- ooh boy, are the steps to get a clean, reasonable Android dev environment ever changing and confusing even to someone experienced. I'm very happy to see CRNA presented as a starter.

We should of course highlight in the same guide that there is an option that entails setting up the entire development environment. For people experienced with building native apps who already have most or all of the environment set up, the steps for them to follow may very well be minimal and yet a more interesting route to take than CRNA (run your apps directly in the simulator/AVD/devices you already have, no need to install Expo or worry about reachability in your network!). Nevertheless, this should be the "Expert" portion of the guide, presented after CRNA.

It's not *technically* accurate to say it only works in native built apps, since the CRNA entry point does in fact call this indirectly, but CRNA does handle it for you.

Because the native-relevant sections are spread out around the guide currently, it seems prudent to create a separate section for them so that only a single "native builds needed" banner is needed. This reduces visual clutter and progressively discloses information to the reader based on their skill level and the complexity of their app. Also adds a couple of notes to the ejected subsections that CRNA handles certain things for you already.

anp · 2017-04-07T00:32:04Z

So of the items I identified as needing work, the only outstanding question I have is how to handle the fact that CRNA will lag stable RN releases by a week or so. This has already come up as a potential source of confusion (c.f. expo/create-react-native-app#151), but I'm not sure whether there's a way to make this smooth. Presumably people who care about a particular RN version before CRNA catches up are already "advanced users" and will have ejected or be willing/able to do their own native builds.

I'm definitely open to suggestions as to whether it's something we could/should handle at all in the docs. @hramos, I think this is probably ready for review whenever you have time unless you have any insight about handling that version lag.

peterp · 2017-04-07T07:11:06Z

Thanks @dikaiosune, I appreciate you taking the time to ease my concerns, and I appreciate the way that you're attempting to decrease the barrier of entry for people interested in React Native.

hramos

I have some minor feedback but generally I'm good with merging this. I'd also like to hear your thoughts on React's updated installation guide, which now has separate tabs for each alternative (see https://facebook.github.io/react/docs/installation.html, these tabs were added after this PR was opened).

I like the way they open with a question: do you want to create a new React app, add React to an existing app, or just try out React?

I think this is something we can explore in another PR.

hramos · 2017-04-24T14:04:13Z

+
+[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 native build tools.
+
+Assuming that you have Node installed, no Xcode or Android Studio installation is required:


The phrasing here seems a bit odd to me (but keep in mind, English is my second language). The way I read it, Xcode or Android Studio may be required if I don't have Node installed.
Maybe we can split into two sentences, and swap the order? Something like:

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 projected called "AwesomeProject":

I'm mirroring the instructions for Native Builds at the end here, "AwesomeProject" could be anything but ideally it would match the original RN init commands.

After this PR gets merged I'll probably take another pass at updating the Getting Started guide and subsequent pages, as I'd like to update the tutorial so that it builds on top of the CRNA started project similar to what we did at F8 this year.

hramos · 2017-04-24T14:04:59Z

+
+```
+npm install -g create-react-native-app
+create-react-native-app hello-world


Change this and the next line to AwesomeApp (or update the instructions for RN init to use "hello-world", too)

hramos · 2017-04-24T14:07:54Z

+
+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. The QR scanner is available under the "Projects" tab of the app. 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.


I think we can leave out "The QR scanner is available under the Projects tab of the app". When I launch the Expo app, the Projects tab is visible by default and I can see a "Scan QR Code" callout at the top so it seems people can figure this out.

I don't feel too strongly about this though, if for example you've found that Expo users tend to be confused by this bit then we can leave this in.

hramos · 2017-04-24T14:10:32Z

+
+Once you've created your project and opened it in the Expo client app, you can proceed to the [Tutorial](docs/tutorial.html).
+
+### Caveats


Ideally we'd have a standalone CRNA doc that covers any caveats, as well as the ejection process. We can tackle that in a different PR though, I'm OK with this section here for now.

hramos · 2017-04-24T14:11:12Z

+
+### 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.


Looks good to me, once we have a CRNA doc we can be more verbose there.

hramos · 2017-04-24T14:11:49Z

+
+<hr style="margin-top:25px"/>
+
+## Native Builds


I'm not sure about this section title yet but I don't have a better suggestion just yet shrug

Alternatives I see right off the bat:

Building with Xcode and Android Studio

Custom Build Environment

Building with Custom Native Code

Building Your Own Native Code

I've been thinking about this and have currently landed on these two terms to distinguish between the two types of React Native projects people might be working with:

Create-React-Native-App Projects

Projects with Native Code

The second one covers any project created using react-native init, or using CRNA but has since "ejected".

If we use these terms, then this section could be named "Building Projects with Native Code". Thoughts?

hramos · 2017-04-24T14:13:31Z

+
+## Native Builds
+
+Follow these instructions if you need your own native build configuration. 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.


Maybe explain that, if you "ejected" or are integrating into an existing app, you will need to setup all the dependencies covered in this section. The idea would be to make it clear RN init is not necessary (as you already have a project). To me it's obvious RN init is not needed, but it may not be clear to a new user if RN init does some additional, required setup.

That's a great point. What do you think about making the example commands something like this?

# skip this first command if you ejected from Create React Native App react-native init AwesomeProject cd AwesomeProject react-native run-ios

I think that's the most likely place for users to see it, but it might be better to have a more thorough explanation elsewhere? Doing both might be too much given the limited real estate, but I'm very open to suggestions here.

OK, I pushed up a commit that implements the example I previously commented, let me know if you think it's too clunky or should be moved to a central location?

hramos · 2017-04-24T14:15:23Z

 *
 * 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.


/me pours one out for Parse.

anp · 2017-04-24T18:51:38Z

Thanks for the review @hramos!

I agree that the React tabs are quite handsome, and I also agree it would be good to provide users better ways to self-select into the various paths here. I'm not sure what the options would be exactly, because in addition to React's motivations we also have "start a new app where I know that I need my own native code." I'll think about this more and we can chat about it when discussing the dedicated CRNA page?

facebook-github-bot · 2017-04-25T22:49:10Z

@hramos has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

facebook-github-bot · 2017-04-26T11:48:50Z

I tried to merge this pull request into the Facebook internal repo but some checks failed. To unblock yourself please check the following: Does this pull request pass all open source tests on GitHub? If not please fix those. Does the code still apply cleanly on top of GitHub master? If not can please rebase. In all other cases this means some internal test failed, for example a part of a fb app won't work with this pull request. I've added the Import Failed label to this pull request so it is easy for someone at fb to find the pull request and check what failed. If you don't see anyone comment in a few days feel free to comment mentioning one of the core contributors to the project so they get a notification.

anp added 2 commits April 4, 2017 14:11

Add Create React Native App to Getting Started.

0edc6e0

Add "ejected only" banner to native code guides.

ac7858f

facebook-github-bot added GH Review: review-needed CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. labels Apr 4, 2017

anp commented Apr 4, 2017

View reviewed changes

skevy requested a review from hramos April 4, 2017 22:50

hramos self-assigned this Apr 5, 2017

hramos added the Documentation label Apr 5, 2017

anp added 6 commits April 6, 2017 12:19

Remove CRNA from More Resources.

73d3f80

Add "Native Builds Only" banner to Geolocation API configuration.

8fbd3fe

Add "Native Builds Only" banner to PushNotificationIOS page.

892e171

Add native build banner to PermissionsAndroid API page.

c1cbecd

Add native build banner to Linking API.

9e733e2

This is partially supported in CRNA right now, but it will be a month or two before we can figure out full support for all of the methods.

anp added 2 commits April 6, 2017 16:54

Add native builds banner to AppRegistry.

d5f7416

It's not *technically* accurate to say it only works in native built apps, since the CRNA entry point does in fact call this indirectly, but CRNA does handle it for you.

hramos approved these changes Apr 24, 2017

View reviewed changes

anp added 2 commits April 24, 2017 10:47

Update getting started language for clarity & parity.

c124004

Address nit re: Expo use instructions.

ffd4444

anp mentioned this pull request Apr 24, 2017

New heading clarifies the usage of AppRegistry #13601

Closed

anp and others added 8 commits April 25, 2017 15:15

Tell users to skip r-n init if they ejected.

054ad90

Rename "Native Builds" section.

54b0e88

Update EjectBanner.js

31c7ebc

Update Debugging.md

1d9b520

Update Geolocation.js

563c0c5

Update Linking.js

6ffeafa

Update PushNotificationIOS.js

dd51bf9

"Projects with Native Code" everywhere.

0837787

facebook-github-bot added GH Review: accepted Import Started This pull request has been imported. This does not imply the PR has been approved. and removed GH Review: review-needed labels Apr 25, 2017

facebook-github-bot added Import Failed and removed Import Started This pull request has been imported. This does not imply the PR has been approved. labels Apr 26, 2017

facebook-github-bot closed this in 0c9b41f Apr 26, 2017

anp deleted the crna-in-docs branch April 26, 2017 17:51


		[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 native build tools.

		Assuming that you have Node installed, no Xcode or Android Studio installation is required:


		Once you've created your project and opened it in the Expo client app, you can proceed to the [Tutorial](docs/tutorial.html).

		### Caveats


		### 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'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"/>


		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. The QR scanner is available under the "Projects" tab of the app. 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.


		## Native Builds

		Follow these instructions if you need your own native build configuration. 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.

Conversation

anp commented Apr 4, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Test Plan

TODO before merging

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anp Apr 4, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brentvatne commented Apr 5, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anp commented Apr 5, 2017

Uh oh!

peterp commented Apr 5, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anp commented Apr 6, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hramos commented Apr 6, 2017

Uh oh!

anp commented Apr 7, 2017

Uh oh!

peterp commented Apr 7, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hramos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anp commented Apr 24, 2017

Uh oh!

facebook-github-bot commented Apr 25, 2017

Uh oh!

anp commented Apr 4, 2017 •

edited

Loading

anp Apr 4, 2017 •

edited

Loading

brentvatne commented Apr 5, 2017 •

edited

Loading

peterp commented Apr 5, 2017 •

edited

Loading

anp commented Apr 6, 2017 •

edited

Loading

peterp commented Apr 7, 2017 •

edited

Loading