@samitouri / QOS-React / commits / db140c887f

Explain Installation in more detail

Dan Abramov committed Nov 17, 2016 at 15:55 UTC db140c887f389995b8be2ddbfb33601b49708c12
1 file changed +56 -12
docs/docs/installation.md
+56 -12
@@ -31,19 +31,49 @@ cd hello-world
31 npm start
32 ```
33
34 -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. It uses Webpack, Babel and ESLint under the hood, but configures them for you.
34 +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. It uses [webpack](https://webpack.js.org/), [Babel](http://babeljs.io/) and [ESLint](http://eslint.org/) under the hood, but configures them for you.
35
36 ## Adding React to an Existing Application
37
38 -### Using npm
38 +You don't need to rewrite your app to start using React.
39
40 -We recommend using React from npm with a bundler like [Browserify](http://browserify.org/) or [webpack](https://webpack.github.io/). If you use npm for client package management, you can install React with:
40 +We recommend adding React to a small part of your application, such an individual widget, so you can see if it works well for your use case.
41 +
42 +While React [can be used](/react/docs/react-without-es6.html) without a build pipeline, we recommend setting it up so you can be more productive. A modern build pipeline typically consists of:
43 +
44 +* A **package manager**, such as [Yarn](https://yarnpkg.com/) or [npm](https://www.npmjs.com/). It lets you take advantage of a vast ecosystem of third-party packages, and easily install or update them.
45 +* A **bundler**, such as [webpack](https://webpack.github.io/) or [Browserify](http://browserify.org/). It lets you write modular code and bundle it together into small packages to optimize load time.
46 +* A **compiler** such as [Babel](http://babeljs.io/). It lets you write modern JavaScript code that still works in older browsers.
47 +
48 +### Installing React
49 +
50 +We recommend using [Yarn](https://yarnpkg.com/) or [npm](https://www.npmjs.com/) for managing front-end dependencies. If you're new to package managers, [Yarn documentation](https://yarnpkg.com/en/docs/getting-started) is a good place to get started.
51 +
52 +To install React with Yarn, run:
53 +
54 +```bash
55 +yarn add react react-dom
56 +```
57 +
58 +To install React with npm, run:
59
60 ```bash
61 npm install --save react react-dom
62 ```
63
46 -and import it from your code with something like:
64 +Both yarn and npm work with the npm registry.
65 +
66 +### Enabling ES6 and JSX
67 +
68 +We recommend using React with [Babel](http://babeljs.io/) to let you use ES6 and JSX in your JavaScript code. ES6 is a set of modern JavaScript features that make development easier, and JSX is an extension to the JavaScript language that works nicely with React.
69 +
70 +The [Babel setup instructions](https://babeljs.io/docs/setup/) explain how to configure Babel in many different build environments. Make sure you install [`babel-preset-react`](http://babeljs.io/docs/plugins/preset-react/#basic-setup-with-the-cli-) and [`babel-preset-es2015`](http://babeljs.io/docs/plugins/preset-es2015/#basic-setup-with-the-cli-) and enable them in your [`.babelrc` configuration](http://babeljs.io/docs/usage/babelrc/), and you're good to go.
71 +
72 +### Hello World with ES6 and JSX
73 +
74 +We recommend using a bundler like [webpack](https://webpack.github.io/) or [Browserify](http://browserify.org/) so you can write modular code and bundle it together into small packages to optimize load time.
75 +
76 +The smallest React example looks like this:
77
78 ```js
79 import React from 'react';
@@ -55,28 +85,42 @@ ReactDOM.render(
85 );
86 ```
87
58 -This code renders into an HTML element with the id of `root` so you need `<div id="root"></div>` somewhere in your HTML file. When you use React in this way, you should be transpiling your JavaScript using Babel with the `es2015` and `react` presets. To use React in production mode, set the environment variable `NODE_ENV` to `"production"`.
88 +This code renders into a DOM element with the id of `root` so you need `<div id="root"></div>` somewhere in your HTML file.
89
60 -If you use Bower, React is available via the `react` package.
90 +Similarly, you can render a React component inside a DOM element somewhere inside your existing app written with any other JavaScript UI library.
91
62 -### Enabling ES6 and JSX
92 +### Development and Production Versions
93 +
94 +By default, React includes many helpful warnings. These warnings are very useful in development. However, they make React larger and slower so you should make sure to use the production version when you deploy the app.
95 +
96 +#### Create React App
97 +
98 +If you use [Create React App](https://github.com/facebookincubator/create-react-app), `npm run build` will create an optimized build of your app in the `build` folder.
99 +
100 +#### Webpack
101 +
102 +Include both `DefinePlugin` and `UglifyJsPlugin` into your production Webpack configuration as described in [this guide](https://webpack.js.org/guides/production-build/).
103
64 -We recommend using React with Babel to let you use ES6 and JSX in your JavaScript code. ES6 is a set of modern JavaScript features that make development easier, and JSX is an extension to the JavaScript language that works nicely with React. The [Babel setup instructions](https://babeljs.io/docs/setup/) explain how to configure Babel in many different build environments. Make sure you install `babel-preset-react` and `babel-preset-es2015` and enable them in your `.babelrc`, and you're good to go.
104 +#### Browserify
105 +
106 +Run Browserify with `NODE_ENV` environment variable set to `production` and use [UglifyJS](https://github.com/mishoo/UglifyJS) as the last build step so that development-only code gets stripped out.
107
108 ### Using a CDN
109
68 -If you don't want to use npm to manage client packages, the `react` and `react-dom` npm packages also provide UMD distributions in `dist` folders, which are hosted on a CDN:
110 +If you don't want to use npm to manage client packages, the `react` and `react-dom` npm packages also provide single-file distributions in `dist` folders, which are hosted on a CDN:
111
112 ```html
113 <script src="https://unpkg.com/react@15/dist/react.js"></script>
114 <script src="https://unpkg.com/react-dom@15/dist/react-dom.js"></script>
115 ```
116
75 -To load a specific version of `react` and `react-dom`, replace `15` with the version number.
76 -
77 -Minified production versions of React are available at:
117 +The versions above are only meant for development, and are not suitable for production. Minified and optimized production versions of React are available at:
118
119 ```html
120 <script src="https://unpkg.com/react@15/dist/react.min.js"></script>
121 <script src="https://unpkg.com/react-dom@15/dist/react-dom.min.js"></script>
122 ```
123 +
124 +To load a specific version of `react` and `react-dom`, replace `15` with the version number.
125 +
126 +If you use Bower, React is available via the `react` package.