Create section on using React with package managers.
Jim committed
Feb 29, 2016 at 12:47 UTC
c01c46b88aa07b4c735b110a5a49e9dd88d83acc
6 files changed
+219
-164
docs/_data/nav_docs.yml
+5
@@ -48,6 +48,11 @@
48
title: Refs to Components
49
- id: tooling-integration
50
title: Tooling Integration
51
+ subitems:
52
+ - id: language-tooling
53
+ title: Language Tooling
54
+ - id: package-management
55
+ title: Package Management
56
- id: addons
57
title: Add-Ons
58
subitems:
docs/docs/09-tooling-integration.md
+4
-71
@@ -3,78 +3,11 @@ id: tooling-integration
3
title: Tooling Integration
4
permalink: tooling-integration.html
5
prev: more-about-refs.html
6
-next: addons.html
6
+next: language-tooling.html
7
---
8
9
-Every project uses a different system for building and deploying JavaScript. We've tried to make React as environment-agnostic as possible.
9
+We've tried to make React as environment-agnostic as possible. People use React in a variety of languages (JavaScript, TypeScript, ClojureScript, etc) and in a variety of environments (web, iOS, Android, NodeJS, Nashorn, etc). There are many tools to help you build great applications. In these sections we introduce some of the tools that are most commonly used together with React.
10
11
-## React
11
+* [Language Tooling](/react/docs/language-tooling.html) describes how to set up tools like Babel to transpile JSX for a better development experience.
12
+* [Package Management](/react/docs/package-management.html) describes how to configure React as a dependency of your project.
13
13
-### CDN-hosted React
14
-
15
-We provide CDN-hosted versions of React [on our download page](/react/downloads.html). These pre-built files use the UMD module format. Dropping them in with a simple `<script>` tag will inject a `React` global into your environment. It should also work out-of-the-box in CommonJS and AMD environments.
16
-
17
-### Using master
18
-
19
-We have instructions for building from `master` [in our GitHub repository](https://github.com/facebook/react). We build a tree of CommonJS modules under `build/modules` which you can drop into any environment or packaging tool that supports CommonJS.
20
-
21
-## JSX
22
-
23
-### In-browser JSX Transform
24
-
25
-If you like using JSX, Babel 5 provided an in-browser ES6 and JSX transformer for development called browser.js that can be included from [CDNJS](http://cdnjs.com/libraries/babel-core/5.8.34). Include a `<script type="text/babel">` tag to engage the JSX transformer.
26
-
27
-> Note:
28
->
29
-> The in-browser JSX transformer is fairly large and results in extraneous computation client-side that can be avoided. Do not use it in production — see the next section.
30
-
31
-### Productionizing: Precompiled JSX
32
-
33
-If you have [npm](https://www.npmjs.com/), you can run `npm install -g babel-cli`. Babel has built-in support for React v0.12+. Tags are automatically transformed to their equivalent `React.createElement(...)`, `displayName` is automatically inferred and added to all `React.createClass` calls.
34
-
35
-This tool will translate files that use JSX syntax to plain JavaScript files that can run directly in the browser. It will also watch directories for you and automatically transform files when they are changed; for example: `babel --watch src/ --out-dir lib/`.
36
-
37
-Beginning with Babel 6, there are no transforms included by default. This means that options must be specified when running the `babel` command, or a `.babelrc` must specify options. Additional packages must also be installed which bundle together a number of transforms, called presets. The most common use when working with React will be to include the `es2015` and `react` presets. More information about the changes to Babel can be found in [their blog post announcing Babel 6](http://babeljs.io/blog/2015/10/29/6.0.0/).
38
-
39
-Here is an example of what you will do if using ES2015 syntax and React:
40
-
41
-```
42
-npm install babel-preset-es2015 babel-preset-react
43
-babel --presets es2015,react --watch src/ --out-dir lib/
44
-```
45
-
46
-By default JSX files with a `.js` extension are transformed. Run `babel --help` for more information on how to use Babel.
47
-
48
-Example output:
49
-
50
-```
51
-$ cat test.jsx
52
-var HelloMessage = React.createClass({
53
- render: function() {
54
- return <div>Hello {this.props.name}</div>;
55
- }
56
-});
57
-
58
-ReactDOM.render(<HelloMessage name="John" />, mountNode);
59
-$ babel test.jsx
60
-"use strict";
61
-
62
-var HelloMessage = React.createClass({
63
- displayName: "HelloMessage",
64
-
65
- render: function render() {
66
- return React.createElement(
67
- "div",
68
- null,
69
- "Hello ",
70
- this.props.name
71
- );
72
- }
73
-});
74
-
75
-ReactDOM.render(React.createElement(HelloMessage, { name: "John" }), mountNode);
76
-```
77
-
78
-### Helpful Open-Source Projects
79
-
80
-The open-source community has built tools that integrate JSX with several editors and build systems. See [JSX integrations](https://github.com/facebook/react/wiki/Complementary-Tools#jsx-integrations) for the full list.
docs/docs/09.1-language-tooling.md
new
+79
@@ -0,0 +1,79 @@
1
+---
2
+id: language-tooling
3
+title: Language Tooling
4
+permalink: language-tooling.html
5
+prev: tooling-integration.html
6
+next: package-management.html
7
+---
8
+
9
+## ES2015 with JSX
10
+
11
+### In-browser JSX Transform
12
+
13
+If you like using JSX, Babel 5 provided an in-browser ES2015 and JSX transformer for development called browser.js that can be included from [CDNJS](https://cdnjs.com/libraries/babel-core/5.8.34). Include a `<script type="text/babel">` tag to engage the JSX transformer.
14
+
15
+> Note:
16
+>
17
+> The in-browser JSX transformer is fairly large and results in extraneous computation client-side that can be avoided. Do not use it in production — see the next section.
18
+
19
+### Productionizing: Precompiled JSX
20
+
21
+If you have [npm](https://www.npmjs.com/), you can run `npm install -g babel-cli`. Babel has built-in support for React v0.12+. Tags are automatically transformed to their equivalent `React.createElement(...)`, `displayName` is automatically inferred and added to all `React.createClass` calls.
22
+
23
+This tool will translate files that use JSX syntax to plain JavaScript files that can run directly in the browser. It will also watch directories for you and automatically transform files when they are changed; for example: `babel --watch src/ --out-dir lib/`.
24
+
25
+Beginning with Babel 6, there are no transforms included by default. This means that options must be specified when running the `babel` command, or a `.babelrc` must specify options. Additional packages must also be installed which bundle together a number of transforms, called presets. The most common use when working with React will be to include the `es2015` and `react` presets. More information about the changes to Babel can be found in [their blog post announcing Babel 6](http://babeljs.io/blog/2015/10/29/6.0.0).
26
+
27
+Here is an example of what you will do if using ES2015 syntax and React:
28
+
29
+```
30
+npm install babel-preset-es2015 babel-preset-react
31
+babel --presets es2015,react --watch src/ --out-dir lib/
32
+```
33
+
34
+By default JSX files with a `.js` extension are transformed. Run `babel --help` for more information on how to use Babel.
35
+
36
+Example output:
37
+
38
+```
39
+$ cat test.js
40
+var HelloMessage = React.createClass({
41
+ render: function() {
42
+ return <div>Hello {this.props.name}</div>;
43
+ }
44
+});
45
+
46
+ReactDOM.render(<HelloMessage name="John" />, mountNode);
47
+$ babel test.js
48
+"use strict";
49
+
50
+var HelloMessage = React.createClass({
51
+ displayName: "HelloMessage",
52
+
53
+ render: function render() {
54
+ return React.createElement(
55
+ "div",
56
+ null,
57
+ "Hello ",
58
+ this.props.name
59
+ );
60
+ }
61
+});
62
+
63
+ReactDOM.render(React.createElement(HelloMessage, { name: "John" }), mountNode);
64
+```
65
+
66
+### Helpful Open-Source Projects
67
+
68
+The open-source community has built tools that integrate JSX with several editors and build systems. See [JSX integrations](https://github.com/facebook/react/wiki/Complementary-Tools#jsx-integrations) for the full list.
69
+
70
+## Flow
71
+
72
+Flow is a JavaScript type checker released by Facebook, and it supports JSX. For more info, checkout the [Flow homepage](http://flowtype.org/).
73
+
74
+
75
+## TypeScript
76
+
77
+Microsoft TypeScript now supports JSX. For more info, check out the [TypeScript JSX Documentation](http://www.typescriptlang.org/docs/handbook/jsx.html) or their guide on [getting started with react+webpack](https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/quick-start/react-webpack.md).
78
+
79
+
docs/docs/09.2-package-management.md
new
+126
@@ -0,0 +1,126 @@
1
+---
2
+id: package-management
3
+title: Package Management
4
+permalink: package-management.html
5
+prev: language-tooling.html
6
+next: addons.html
7
+---
8
+
9
+## CDN-hosted React
10
+
11
+We provide CDN-hosted versions of React [on our download page](/react/downloads.html). These pre-built files use the UMD module format. Dropping them in with a simple `<script>` tag will inject the `React` and `ReactDOM` globals into your environment. It should also work out-of-the-box in CommonJS and AMD environments.
12
+
13
+
14
+## Using React from npm
15
+
16
+You can use React with a CommonJS module system like [browserify](http://browserify.org/) or [webpack](https://webpack.github.io/). Use the [`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) npm packages.
17
+
18
+```js
19
+// main.js
20
+var React = require('react');
21
+var ReactDOM = require('react-dom');
22
+
23
+ReactDOM.render(
24
+ <h1>Hello, world!</h1>,
25
+ document.getElementById('example')
26
+);
27
+```
28
+
29
+Configure [babel](https://babeljs.io/) with a `.babelrc` file:
30
+
31
+ ```json
32
+ { "presets": ["react"] }
33
+ ```
34
+
35
+ > Note:
36
+ >
37
+ > If you are using ES2015, you will want to also use the `babel-preset-es2015` package.
38
+
39
+
40
+To install React DOM and build your bundle with browserify:
41
+
42
+```sh
43
+$ npm install --save react react-dom babelify babel-preset-react
44
+$ browserify -t [ babelify ] main.js -o bundle.js
45
+```
46
+
47
+To install React DOM and build your bundle with webpack:
48
+
49
+```sh
50
+$ npm install --save react react-dom babel-preset-react babel-loader babel-core
51
+$ webpack main.js bundle.js --module-bind 'js=babel-loader'
52
+```
53
+
54
+> Note:
55
+>
56
+> If you are using ES2015, you will want to also use the `babel-preset-es2015` package.
57
+
58
+**Note:** by default, React will be in development mode, which is slower, and not advised for production. To use React in production mode, set the environment variable `NODE_ENV` to `production` (using envify or webpack's DefinePlugin). For example:
59
+
60
+```js
61
+new webpack.DefinePlugin({
62
+ "process.env": {
63
+ NODE_ENV: JSON.stringify("production")
64
+ }
65
+});
66
+```
67
+
68
+Update your HTML file as below:
69
+
70
+```html{8,12}
71
+<!DOCTYPE html>
72
+<html>
73
+ <head>
74
+ <meta charset="UTF-8" />
75
+ <title>Hello React!</title>
76
+ <script src="build/react.js"></script>
77
+ <script src="build/react-dom.js"></script>
78
+ <!-- No need for Babel! -->
79
+ </head>
80
+ <body>
81
+ <div id="example"></div>
82
+ <script src="build/helloworld.js"></script>
83
+ </body>
84
+</html>
85
+```
86
+
87
+## Using React from Bower
88
+
89
+Bower is a package manager optimized for the front-end development. If multiple packages depend on a package - jQuery for example - Bower will download jQuery just once. This is known as a flat dependency graph and it helps reduce page load. For more info, visit http://bower.io/
90
+
91
+If you'd like to use bower, it's as easy as:
92
+
93
+```
94
+bower install --save react
95
+```
96
+
97
+```html
98
+<!DOCTYPE html>
99
+
100
+
101
+
102
+<html>
103
+ <head>
104
+ <meta charset="UTF-8" />
105
+ <title>Hello React!</title>
106
+ <script src="bower_components/react/react.js"></script>
107
+ <script src="bower_components/react/react-dom.js"></script>
108
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.23/browser.min.js"></script>
109
+ </head>
110
+ <body>
111
+ <div id="example"></div>
112
+ <script type="text/babel">
113
+ ReactDOM.render(
114
+ <h1>Hello, world!</h1>,
115
+ document.getElementById('example')
116
+ );
117
+ </script>
118
+ </body>
119
+</html>
120
+```
121
+
122
+
123
+## Using master
124
+
125
+We have instructions for building from `master` [in our GitHub repository](https://github.com/facebook/react).
126
+
docs/docs/10-addons.md
+1
-1
@@ -2,7 +2,7 @@
2
id: addons
3
title: Add-ons
4
permalink: addons.html
5
-prev: tooling-integration.html
5
+prev: package-management.html
6
next: animation.html
7
---
8
docs/docs/getting-started.md
+4
-92
@@ -12,52 +12,10 @@ The easiest way to start hacking on React is using the following JSFiddle Hello
12
* **[React JSFiddle](https://jsfiddle.net/reactjs/69z2wepo/)**
13
* [React JSFiddle without JSX](https://jsfiddle.net/reactjs/5vjqabv3/)
14
15
-## Using React from npm
15
17
-We recommend using React with a CommonJS module system like [browserify](http://browserify.org/) or [webpack](https://webpack.github.io/). Use the [`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) npm packages.
16
+## Starter Pack
17
19
-```js
20
-// main.js
21
-var React = require('react');
22
-var ReactDOM = require('react-dom');
23
-
24
-ReactDOM.render(
25
- <h1>Hello, world!</h1>,
26
- document.getElementById('example')
27
-);
28
-```
29
-
30
-To install React DOM and build your bundle with browserify:
31
-
32
-```sh
33
-$ npm install --save react react-dom babelify babel-preset-react
34
-$ browserify -t [ babelify --presets [ react ] ] main.js -o bundle.js
35
-```
36
-
37
-To install React DOM and build your bundle with webpack:
38
-
39
-```sh
40
-$ npm install --save react react-dom babel-preset-react
41
-$ webpack
42
-```
43
-
44
-> Note:
45
->
46
-> If you are using ES2015, you will want to also use the `babel-preset-es2015` package.
47
-
48
-**Note:** by default, React will be in development mode, which is slower, and not advised for production. To use React in production mode, set the environment variable `NODE_ENV` to `production` (using envify or webpack's DefinePlugin). For example:
49
-
50
-```js
51
-new webpack.DefinePlugin({
52
- "process.env": {
53
- NODE_ENV: JSON.stringify("production")
54
- }
55
-});
56
-```
57
-
58
-## Quick Start Without npm
59
-
60
-If you're not ready to use npm yet, you can download the starter kit which includes prebuilt copies of React and React DOM.
18
+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.
19
20
<div class="buttons-unit downloads">
21
<a href="/react/downloads/react-{{site.react_version}}.zip" class="button">
@@ -110,58 +68,12 @@ Then reference it from `helloworld.html`:
68
69
Note that some browsers (Chrome, e.g.) will fail to load the file unless it's served via HTTP.
70
113
-### Offline Transform
114
-
115
-First install the [Babel](http://babeljs.io/) command-line tools (requires [npm](https://www.npmjs.com/)):
71
+## Using React with npm or Bower
72
117
-```
118
-npm install --global babel-cli
119
-npm install babel-preset-react
120
-```
121
-
122
-Then, translate your `src/helloworld.js` file to plain JavaScript:
123
-
124
-```
125
-babel --presets react src --watch --out-dir build
126
-```
127
-
128
-> Note:
129
->
130
-> If you are using ES2015, you will want to also use the `babel-preset-es2015` package.
131
-
132
-The file `build/helloworld.js` is autogenerated whenever you make a change. Read the [Babel CLI documentation](http://babeljs.io/docs/usage/cli/) for more advanced usage.
133
-
134
-```javascript{2}
135
-ReactDOM.render(
136
- React.createElement('h1', null, 'Hello, world!'),
137
- document.getElementById('example')
138
-);
139
-```
140
-
141
-
142
-Update your HTML file as below:
143
-
144
-```html{8,12}
145
-<!DOCTYPE html>
146
-<html>
147
- <head>
148
- <meta charset="UTF-8" />
149
- <title>Hello React!</title>
150
- <script src="build/react.js"></script>
151
- <script src="build/react-dom.js"></script>
152
- <!-- No need for Babel! -->
153
- </head>
154
- <body>
155
- <div id="example"></div>
156
- <script src="build/helloworld.js"></script>
157
- </body>
158
-</html>
159
-```
73
+You can also use React with package managers like npm or Bower. You can learn more in our [Package Managers](/react/docs/package-management.html) section.
74
75
## Next Steps
76
77
Check out [the tutorial](/react/docs/tutorial.html) and the other examples in the starter kit's `examples` directory to learn more.
78
165
-We also have a wiki where the community contributes with [workflows, UI-components, routing, data management etc.](https://github.com/facebook/react/wiki/Complementary-Tools)
166
-
79
Good luck, and welcome!