Installation instructions #7858

lacker · 2016-10-04T00:18:31Z

This PR combines the information from the "downloads" tab and the "getting started" page into one document.

The home page used to have two calls to action - "downloads" and "getting started". I don't think we need both of those, because they are kinda similar; I think we should make one of them "take the tutorial" instead. For now that points to the old tutorial but we can update it once the new one is in.

There are probably useful details I'm still missing here, so I'd appreciate feedback. I wish there was better advice for people who don't want a single-page app, but also don't already have a build pipeline set up.

Also I updated the fiddle to use ES6 classes so feel free to look at that too

lacker · 2016-10-04T00:19:19Z

gaearon · 2016-10-04T12:37:18Z

docs/_layouts/default.html

        <div class="buttons-unit">
          <a href="/react/docs/getting-started.html" class="button">Get Started</a>
-          <a href="/react/downloads.html" class="button">Download React v{{site.react_version}}</a>
+          <a href="/react/docs/tutorial.html" class="button">Take the Tutorial</a>


Maybe a nit from a non-native speaker, but this:

Reminds me of this.

I honestly wouldn’t know which to choose. If I’m new to React, should I “Get Started” or “Take the Tutorial”? Does taking a tutorial presume I already “got started”? Does “getting started” presume I already know things in the tutorial?

gaearon · 2016-10-04T12:49:00Z

docs/docs/getting-started.md

 ---

-## JSFiddle
+There are several different ways to use React. The right one for you depends on how you're using it.


I think people get a little frustrated when we say there are multiple ways to do the same thing. Maybe approach it from a different angle? e.g.

React is flexible and accommodates a variety of projects. You can create new apps with it, but you can also gradually introduce it into an existing codebase without doing a rewrite.

ok i took most of your wording here

gaearon · 2016-10-04T12:51:17Z

docs/docs/getting-started.md

- * **[React JSFiddle](https://jsfiddle.net/reactjs/69z2wepo/)**
- * [React JSFiddle without JSX](https://jsfiddle.net/reactjs/5vjqabv3/)
+If you're just interested in playing around with React, you can use JSFiddle. Try starting from [this Hello World example code](https://jsfiddle.net/o9gspf3e/). You don't need to install anything; you can just modify the code and click "Run" to see if it works.



I think this section should offer to download an index.html file that lets you play with React. That file would use react@latest and react-dom@latest from unpkg so we wouldn’t need to update it. I don’t think there is a need to write out this file's contents on the page though.

gaearon · 2016-10-04T12:51:42Z

docs/docs/getting-started.md

+## Creating a New Application

-**[Create React App](http://github.com/facebookincubator/create-react-app)** is a new officially supported way to create single-page React applications. It offers a modern build setup with no configuration. It requires Node 4 or higher.
+[`create-react-app`](http://github.com/facebookincubator/create-react-app) is the best way to starting building a new React single page application. It handles webpack, babel, and live reloading, so you don't have to think about them.


I style it as Create React App everywhere, can we keep that instead of the CLI name?

that's weird man but ok

gaearon · 2016-10-04T12:52:30Z

docs/docs/getting-started.md

+If you're just interested in playing around with React, you can use JSFiddle. Try starting from [this Hello World example code](https://jsfiddle.net/o9gspf3e/). You don't need to install anything; you can just modify the code and click "Run" to see if it works.

-## Create React App
+## Creating a New Application


I would say Creating a Single Page Application because this is the specific use case CRA handles. For anything else, you should just use the bundler and do things your way.

I'll change this wording. What is actually the best way to build e.g. a Rails + React non-single-page app? It seems like it might actually be to start with Create React App. But I dunno for sure so I'll hold off on that for now. "Building a new non-single-page-app" seems like it's one of the key omissions here at the moment, but I don't know what to recommend.

Good point. Let's add this as a separate section. It should tell people to:

Either use React from npm or CDN

Add Babel to their asset pipeline (there are many ways) and then ensure they enable 'es2015', 'react' as presets

That Babel link is really exhaustive and includes Rails.

gaearon · 2016-10-04T12:55:43Z

docs/docs/getting-started.md

+npm start
+```
+
+`create-react-app` doesn't handle backend logic or databases; it just creates a frontend build pipeline, so you can use it with any backend you want.


Maybe link to Node and Rails tutorials?

I looked around but it wasn't clear to me what were good Node / Rails tutorials that adhered to best practices. Do you have particular suggestions that you like or have heard good things about? If not, maybe we should just let people Google around themselves.

I linked to the particular ones in the comment 😄
I think these are pretty good as CRA+Node and CRA+Rails intros, not as React intros though.

gaearon · 2016-10-04T12:57:27Z

docs/docs/getting-started.md

+```js
+var React = require('react');
+var ReactDOM = require('react-dom');
+ReactDOM.render(<App />, document.getElementById('the-element-id'));


Let's write the "hello world" App component here inline as a class?

Also let's change document.getElementById('the-element-id') to document.getElementById('root') and mention that you need:

<div id="root"></div> in your HTML file

Babel with react and es2015 presets

gaearon · 2016-10-04T12:59:17Z

docs/docs/getting-started.md

+## Adding React to an Existing Application

-If you're just getting started, you can download the starter kit. The starter kit includes prebuilt copies of React and React DOM for the browser, as well as a collection of usage examples to help you get started.
+We recommend using React from npm with a bundler like [browserify](http://browserify.org/) or [webpack](https://webpack.github.io/). If you already have npm in your build pipeline, you can install it with:


Nit: npm is not a part of the build pipeline.
Maybe "if you use npm for package management"?

gaearon · 2016-10-04T13:00:18Z

docs/docs/getting-started.md

+ReactDOM.render(<App />, document.getElementById('the-element-id'));
+```
+
+If you use Bower, React is available via the `react` package:


Bower should come after a section about UMDs. Right here we should mention that react and react-dom npm packages provide UMD distributions in dist folders, and that we also host the same files on CDN.

gaearon · 2016-10-04T13:02:14Z

docs/docs/getting-started.md

+
+## Using React From A CDN
+
+If you don't have any build pipeline set up, you can still use React directly from a CDN. You also need to load `babel` from a CDN and load your scripts with type `text/babel` so that they can get transformed. This code works as a single html file:


I would completely remove this section. It conflates two different things:

Using React from CDN (fine for dev and prod)

Using in-browser Babel transform (exists only for trying React and literally nothing else)

This section gives a wrong impression that somehow using React from CDN is bad, which it is not.

I think, as I mentioned above, the section on React CDN files should be merged with Adding React to an Existing Application, and the part about in-browser Babel can be fully omitted and instead added to a downloadable index.html in Trying Out React.

lacker · 2016-10-04T16:35:49Z

OK I fixed everything except the call-to-action buttons on the homepage, because it's not clear to me what the right thing is to do. The ideal pages to point to probably don't even exist yet so maybe we can just change it later.

gaearon · 2016-10-04T16:48:36Z

docs/docs/getting-started.md

+```

-If you're just getting started, you can download the starter kit. The starter kit includes prebuilt copies of React and React DOM for the browser, as well as a collection of usage examples to help you get started.
+Create React App doesn't handle backend logic or databases; it just creates a frontend build pipeline, so you can use it with any backend you want.


Let's add here: "It uses Webpack, Babel and ESLint under the hood, but configures them for you."

gaearon · 2016-10-04T16:50:43Z

docs/docs/getting-started.md

-  </a>
-</div>
+## Adding React to an Existing Application



Let's add a section called "Enabling ES6 and JSX" that tells people to use Babel and points to https://babeljs.io/docs/setup/. We can then say something like "make sure you install babel-preset-react and babel-preset-es2015 and enable them in .babelrc, and you're good to go"

gaearon · 2016-10-04T16:52:44Z

docs/downloads/single-file-example.html

+    <title>Hello React World!</title>
+    <script src="https://unpkg.com/react@latest/dist/react.js"></script>
+    <script src="https://unpkg.com/react-dom@latest/dist/react-dom.js"></script>
+    <script src="https://unpkg.com/[email protected]/browser.min.js"></script>


Let's use https://unpkg.com/[email protected]/babel.min.js here instead.
Like in #7669.

lacker added 2 commits October 3, 2016 17:02

more installation instructions

ab9e5d2

cdn instructions

93081df

facebook-github-bot added GH Review: review-needed CLA Signed labels Oct 4, 2016

lacker assigned gaearon Oct 4, 2016

gaearon requested changes Oct 4, 2016

View reviewed changes

lacker added 5 commits October 4, 2016 09:08

fix wording

9ebbb7d

create-react-app -> Create React App

4294b2f

new -> single page

652dd15

fix npm install instructions

53b7d82

break out single html file into its own file

d6faaba

gaearon reviewed Oct 4, 2016

View reviewed changes

gaearon approved these changes Oct 4, 2016

View reviewed changes

lacker added 5 commits October 4, 2016 09:54

merge with Dan's massive docs reorg PR

a3f2de1

another sentence

7993837

use babel standalone

a46ab95

enabling es6 and jsx

057b036

remove old getting started

68566e6

lacker merged commit cb862e1 into facebook:new-docs Oct 4, 2016

lacker deleted the installation branch October 4, 2016 17:52


		## Using React From A CDN

		If you don't have any build pipeline set up, you can still use React directly from a CDN. You also need to load `babel` from a CDN and load your scripts with type `text/babel` so that they can get transformed. This code works as a single html file:

Installation instructions #7858

Installation instructions #7858

Uh oh!

Conversation

lacker commented Oct 4, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lacker commented Oct 4, 2016

Uh oh!

gaearon Oct 4, 2016 • 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!

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!

gaearon Oct 4, 2016 • 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!

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!

lacker commented Oct 4, 2016

Uh oh!

gaearon Oct 4, 2016 • 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lacker commented Oct 4, 2016 •

edited

Loading

gaearon Oct 4, 2016 •

edited

Loading

gaearon Oct 4, 2016 •

edited

Loading

gaearon Oct 4, 2016 •

edited

Loading