Skip to content

Commit 6235231

Browse files
gaearongaearon
authored
Rewrite Installation and related docs (#996)
* Rewrite "adding React to existing app" Fixes #988 * Some copy * typo * Update babel instructions * Update umd link * Add prod minification section * Show "button" example in several targets * wip * More * More * tweak * yas * Multi root tip * moaar * alot * Tweak links * Explain better * better lead * tweaks * tweaks * wording * More reassuring tone * Grammar * wording * feedback from readers * Use id, not class * More nits * Re-add a useful section
1 parent c300c14 commit 6235231

12 files changed

+400
-210
lines changed

‎content/docs/add-react-to-a-new-app.md

Lines changed: 0 additions & 54 deletions
This file was deleted.

‎content/docs/add-react-to-a-website.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
id: add-react-to-a-website
3+
title: Add React to a Website
4+
permalink: docs/add-react-to-a-website.html
5+
redirect_from: "docs/add-react-to-an-existing-app.html"
6+
prev: getting-started.html
7+
next: create-a-new-react-app.html
8+
---
9+
10+
Use as little or as much React as you need.
11+
12+
React is designed for gradual adoption, and **you can use as little or as much React as you need**. Perhaps you only want to add some "sprinkles of interactivity" to an existing page. React components are a great way to do that.
13+
14+
The majority of websites aren't, and don't need to be, single-page apps. With **a few lines of code and no build tooling**, try React in a small part of your website. You can then either gradually expand its presence, or keep it contained to a few dynamic widgets.
15+
16+
---
17+
18+
- [Add React in One Minute](#add-react-in-one-minute)
19+
- [Optional: Try React with JSX](#optional-try-react-with-jsx)
20+
21+
## Add React in One Minute
22+
23+
In this section, we will show how to add a React component to an existing HTML page. You can follow along with your own website, or create an empty HTML file to practice.
24+
25+
There will be no complicated tools or install requirements -- **to complete this section, you only need an internet connection, and a minute of your time.**
26+
27+
Optional: [Download the full example (2KB zipped)](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605/archive/f6c882b6ae18bde42dcf6fdb751aae93495a2275.zip)
28+
29+
### Step 1: Add a DOM Container to the HTML
30+
31+
First, open the HTML page you want to edit. Add an empty `<div>` tag to mark the spot where you want to display something with React. For example:
32+
33+
```html{3}
34+
<!-- ... existing HTML ... -->
35+
36+
<div id="like_button_container"></div>
37+
38+
<!-- ... existing HTML ... -->
39+
```
40+
41+
We gave this `<div>` a unique `id` HTML attribute. This will allow us to find it from the JavaScript code later and display a React component inside of it.
42+
43+
>Tip
44+
>
45+
>You can place a "container" `<div>` like this **anywhere** inside the `<body>` tag. You may have as many independent DOM containers on one page as you need. They are usually empty -- React will replace any existing content inside DOM containers.
46+
47+
### Step 2: Add the Script Tags
48+
49+
Next, add three `<script>` tags to the HTML page right before the closing `</body>` tag:
50+
51+
```html{5,6,9}
52+
<!-- ... other HTML ... -->
53+
54+
<!-- Load React. -->
55+
<!-- Note: when deploying, replace "development.js" with "production.min.js". -->
56+
<script src="https://unpkg.com/react@16/umd/react.development.js" crossorigin></script>
57+
<script src="https://unpkg.com/react-dom@16/umd/react-dom.development.js" crossorigin></script>
58+
59+
<!-- Load our React component. -->
60+
<script src="like_button.js"></script>
61+
62+
</body>
63+
```
64+
65+
The first two tags load React. The third one will load your component code.
66+
67+
### Step 3: Create a React Component
68+
69+
Create a file called `like_button.js` next to your HTML page.
70+
71+
Open this [this starter code](https://cdn.rawgit.com/gaearon/0b180827c190fe4fd98b4c7f570ea4a8/raw/b9157ce933c79a4559d2aa9ff3372668cce48de7/LikeButton.js) and paste it into the file you created.
72+
73+
>Tip
74+
>
75+
>This code defines a React component called `LikeButton`. Don't worry if you don't understand it yet -- we'll cover the building blocks of React later in our [main concepts guide](/docs/hello-world.html) and a [hands-on tutorial](/tutorial/tutorial.html). For now, let's just get it showing on the screen!
76+
77+
After the starter code, add two lines to the bottom of `like_button.js`:
78+
79+
```js{3,4}
80+
// ... the starter code you pasted ...
81+
82+
const domContainer = document.querySelector('#like_button_container');
83+
ReactDOM.render(e(LikeButton), domContainer);
84+
```
85+
86+
These two lines of code find the `<div>` we added to our HTML in the first step, and then display our "Like" button React component inside of it.
87+
88+
### That's It!
89+
90+
There is no step four. **You have just added the first React component to your website.**
91+
92+
Check out the next sections for more tips on integrating React.
93+
94+
**[View the full example source code](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605)**
95+
96+
**[Download the full example (2KB zipped)](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605/archive/f6c882b6ae18bde42dcf6fdb751aae93495a2275.zip)**
97+
98+
### Tip: Reuse a Component
99+
100+
Commonly, you might want to display React components in multiple places on the HTML page. Here is an example that displays the "Like" button three times and passes some data to it:
101+
102+
[View the full example source code](https://gist.github.com/gaearon/faa67b76a6c47adbab04f739cba7ceda)
103+
104+
[Download the full example (2KB zipped)](https://gist.github.com/gaearon/faa67b76a6c47adbab04f739cba7ceda/archive/9d0dd0ee941fea05fd1357502e5aa348abb84c12.zip)
105+
106+
>Note
107+
>
108+
>This strategy is mostly useful while React-powered parts of the page are isolated from each other. Inside React code, it's easier to use [component composition](/docs/components-and-props.html#composing-components) instead.
109+
110+
### Tip: Minify JavaScript for Production
111+
112+
Before deploying your website to production, be mindful that unminifed JavaScript can significantly slow down the page for your users.
113+
114+
If you already minify the application scripts, **your site will be production-ready if you ensure that the deployed HTML loads the versions of React ending in `production.min.js`:**
115+
116+
```js
117+
<script src="https://unpkg.com/react@16/umd/react.production.min.js" crossorigin></script>
118+
<script src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js" crossorigin></script>
119+
```
120+
121+
If you don't have a minification step for your scripts, [here's one way to set it up](https://gist.github.com/gaearon/42a2ffa41b8319948f9be4076286e1f3).
122+
123+
## Optional: Try React with JSX
124+
125+
In the examples above, we only relied on features that are natively supported by the browsers. This is why we used a JavaScript function call to tell React what to display:
126+
127+
```js
128+
const e = React.createElement;
129+
130+
// Display a "Like" <button>
131+
return e(
132+
'button',
133+
{ onClick: () => this.setState({ liked: true }) },
134+
'Like'
135+
);
136+
```
137+
138+
However, React also offers an option to use [JSX](/docs/introducing-jsx.html) instead:
139+
140+
```js
141+
// Display a "Like" <button>
142+
return (
143+
<button onClick={() => this.setState({ liked: true })}>
144+
Like
145+
</button>
146+
);
147+
```
148+
149+
These two code snippets are equivalent. While **JSX is [completely optional](/docs/react-without-jsx.html)**, many people find it helpful for writing UI code -- both with React and with other libraries.
150+
151+
You can play with JSX using [this online converter](http://babeljs.io/repl#?babili=false&browsers=&build=&builtIns=false&spec=false&loose=false&code_lz=Q&debug=false&forceAllTransforms=false&shippedProposals=false&circleciRepo=&evaluate=false&fileSize=false&sourceType=module&lineWrap=true&presets=es2015%2Creact%2Cstage-2%2Cstage-3&prettier=true&targets=Node-6.12&version=6.26.0&envVersion=).
152+
153+
### Add JSX to a Project
154+
155+
If you want to add JSX to your project, follow these three steps:
156+
157+
1. [Install Node.js](https://nodejs.org/)
158+
2. **Don't miss this step:** Run `npm init -y` in your project folder
159+
3. Run `npm install babel-cli@6 babel-preset-react-app@3`
160+
161+
You can now use JSX!
162+
163+
### Compile JSX with One Command
164+
165+
Create create a folder called `src` and run this terminal command:
166+
167+
```
168+
npx babel --watch src --out-dir . --presets react-app/prod
169+
```
170+
171+
>Note
172+
>
173+
>`npx` is not a typo -- it's a [package runner tool that comes with npm 5.2+](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b).
174+
>
175+
>If you see an error message saying "You have mistakingly installed the `babel` package", you might have missed [the previous step](#add-jsx-to-a-project). Perform it in the same folder, and then try again.
176+
177+
This command starts an automated watcher for JSX. For example, if you create `src/like_button.js` with this [JSX starter code](https://cdn.rawgit.com/gaearon/c8e112dc74ac44aac4f673f2c39d19d1/raw/09b951c86c1bf1116af741fa4664511f2f179f0a/like_button.js), Babel will create a compiled `like_button.js` with the plain JavaScript code suitable for the browser. When you edit the JSX file, the transform will re-run automatically.
178+
179+
As a bonus, this will also let you use modern JavaScript syntax features like classes without worrying about breaking older browsers. The tool we just used is called Babel, and you can learn more about it from [its documentation](http://babeljs.io/docs/en/babel-cli/).
180+
181+
If you notice that you're getting comfortable with build tools and want them to do more for you, [the next section](/docs/create-a-new-react-app.html) describes some of the most popular and approachable toolchains. If not -- those script tags will do just fine!

‎content/docs/add-react-to-an-existing-app.md

Lines changed: 0 additions & 96 deletions
This file was deleted.

‎content/docs/cdn-links.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
id: cdn-links
33
title: CDN Links
44
permalink: docs/cdn-links.html
5-
prev: add-react-to-an-existing-app.html
5+
prev: create-a-new-react-app.html
66
next: hello-world.html
77
---
88

9-
The UMD builds of React and ReactDOM are available over a CDN.
9+
Both React and ReactDOM are available over a CDN.
1010

1111
```html
1212
<script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>

0 commit comments

Comments
 (0)