From 4ae00602999d9d4c308e9c0d8150381d1a224405 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Fri, 22 Jun 2018 23:46:20 -0700 Subject: [PATCH 01/21] Rewrite "adding React to existing app" Fixes #988 --- content/docs/add-react-to-an-existing-app.md | 104 +++++++------------ 1 file changed, 38 insertions(+), 66 deletions(-) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index 6381b38ed1d..440bed73a15 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -10,87 +10,59 @@ You don't need to rewrite your app to start using React. We recommend adding React to a small part of your application, such as an individual widget, so you can see if it works well for your use case. -While React [can be used](/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: - -* 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. -* A **bundler**, such as [webpack](https://webpack.js.org/) or [Browserify](http://browserify.org/). It lets you write modular code and bundle it together into small packages to optimize load time. -* A **compiler** such as [Babel](http://babeljs.io/). It lets you write modern JavaScript code that still works in older browsers. - -### Installing React - ->**Note:** -> ->Once installed, we strongly recommend setting up a [production build process](/docs/optimizing-performance.html#use-the-production-build) to ensure you're using the fast version of React in production. - -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, the [Yarn documentation](https://yarnpkg.com/en/docs/getting-started) is a good place to get started. - -To install React with Yarn, run: - -```bash -yarn init -yarn add react react-dom +### 1. Add React [CDN links][cdn] to your HTML + +```html + + ``` -To install React with npm, run: - -```bash -npm init -npm install --save react react-dom -``` - -Both Yarn and npm download packages from the [npm registry](http://npmjs.com/). - -> Note: -> -> To prevent potential incompatibilities, all react packages should use the same version. (This includes `react`, `react-dom`, `react-test-renderer`, etc.) - -### Enabling ES6 and JSX - -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. - -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-env`](http://babeljs.io/docs/plugins/preset-env/) and enable them in your [`.babelrc` configuration](http://babeljs.io/docs/usage/babelrc/), and you're good to go. - -### Hello World with ES6 and JSX - -We recommend using a bundler like [webpack](https://webpack.js.org/) or [Browserify](http://browserify.org/), so you can write modular code and bundle it together into small packages to optimize load time. - -The smallest React example looks like this: +### 2. Write your components ```js -import React from 'react'; -import ReactDOM from 'react-dom'; +// src/widget.js +class Widget extends React.Component() { + render() { + return
Hello, world!
; + } +} ReactDOM.render( -

Hello, world!

, - document.getElementById('root') + , + document.querySelector('.widget') ); ``` -This code renders into a DOM element with the id of `root`, so you need `
` somewhere in your HTML file. +### 3. Compile with Babel -Similarly, you can render a React component inside a DOM element somewhere inside your existing app written with any other JavaScript UI library. +[Babel][babel] is a tool that converts [JSX][jsx] and future JavaScript syntax into ES5 JavaScript compatible with older browsers. -[Learn more about integrating React with existing code.](/docs/integrating-with-other-libraries.html#integrating-with-other-view-libraries) +_Install `babel` with `yarn` or `npm`_ -### A Complete Example - -You can find step-by-step instructions detailing a basic implementation from scratch, including Babel and Webpack setup [here](https://medium.com/@JedaiSaboteur/creating-a-react-app-from-scratch-f3c693b84658). - -### Development and Production Versions +```shell +npm install --global babel-cli babel-preset-react-app +``` -By default, React includes many helpful warnings. These warnings are very useful in development. +_Example: compile files in `src` folder to `build`_ -**However, they make the development version of React larger and slower so you should use the production version when you deploy the app.** +```shell +babel --presets=react-app src -d build +``` -Learn [how to tell if your website is serving the right version of React](/docs/optimizing-performance.html#use-the-production-build), and how to configure the production build process most efficiently: +### 4. Add components to page -* [Creating a Production Build with Create React App](/docs/optimizing-performance.html#create-react-app) -* [Creating a Production Build with Single-File Builds](/docs/optimizing-performance.html#single-file-builds) -* [Creating a Production Build with Brunch](/docs/optimizing-performance.html#brunch) -* [Creating a Production Build with Browserify](/docs/optimizing-performance.html#browserify) -* [Creating a Production Build with Rollup](/docs/optimizing-performance.html#rollup) -* [Creating a Production Build with webpack](/docs/optimizing-performance.html#webpack) +```html + +``` -### Using a CDN + -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 `umd` folders. See the [CDN](/docs/cdn-links.html) page for links. +[babel]: https://babeljs.io +[cdn]: /docs/cdn-links.html +[jsx]: /docs/introducing-jsx.html From ea625996da7a0054238320292b33d61029164685 Mon Sep 17 00:00:00 2001 From: Dan Date: Sat, 23 Jun 2018 14:14:03 +0100 Subject: [PATCH 02/21] Some copy --- content/docs/add-react-to-an-existing-app.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index 440bed73a15..7fbdd2db1e7 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -6,11 +6,15 @@ prev: add-react-to-a-new-app.html next: cdn-links.html --- -You don't need to rewrite your app to start using React. +Use as little, or as much of React as you need. -We recommend adding React to a small part of your application, such as an individual widget, so you can see if it works well for your use case. +While you could [create a single-page app](/docs/add-react-to-a-new-app.html) with React, **the vast majority of the websites aren't, and don't need to be single-page apps**. -### 1. Add React [CDN links][cdn] to your HTML +React has always been designed for progressive adoption, and **you can use as little or as much of React as you need**. Quite often, people only want to add some "sprinkles of interactivity" to an existing page, and React components are a great tool for that. + +In some cases, [more parts of the page become driven by React over time](https://www.youtube.com/watch?v=BF58ZJ1ZQxY), but in others React stays as a flexible and unopinionated tool alongside the existing markup and code. + +### 1. Add React [CDN links](/docs/cdn-links.html) to your HTML ```html ``` - - -[babel]: https://babeljs.io -[cdn]: /docs/cdn-links.html -[jsx]: /docs/introducing-jsx.html From 5d773556d655af7c0f189255a602c48917d3a22f Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Sat, 23 Jun 2018 10:02:55 -0700 Subject: [PATCH 03/21] typo --- content/docs/add-react-to-an-existing-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index 7fbdd2db1e7..9ec7c5fe0bd 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -31,7 +31,7 @@ In some cases, [more parts of the page become driven by React over time](https:/ ```js // src/widget.js -class Widget extends React.Component() { +class Widget extends React.Component { render() { return
Hello, world!
; } From 3a577e053ad15be0f3f61632ba690501bb5e382b Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Sat, 23 Jun 2018 10:29:38 -0700 Subject: [PATCH 04/21] Update babel instructions --- content/docs/add-react-to-an-existing-app.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index 9ec7c5fe0bd..015f336b898 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -19,11 +19,11 @@ In some cases, [more parts of the page become driven by React over time](https:/ ```html ``` @@ -47,15 +47,18 @@ ReactDOM.render( [Babel](https://babeljs.io) is a tool that converts [JSX](/docs/introducing-jsx.html) and future JavaScript syntax into ES5 JavaScript compatible with older browsers. -_Install `babel` with `yarn` or `npm`_ +_Install `babel` with [`yarn`](https://yarnpkg.com) or [`npm`](https://npmjs.com)_ ```shell -npm install --global babel-cli babel-preset-react-app +npm init # if you don't already have a package.json +npm install --global babel-cli +npm install babel-preset-react-app ``` _Example: compile files in `src` folder to `build`_ ```shell +NODE_ENV=development babel --presets=react-app src -d build ``` @@ -64,4 +67,3 @@ babel --presets=react-app src -d build ```html ``` - From 6b6e530897c83d06917aeb79de4fcdd8443aab55 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Sat, 23 Jun 2018 10:48:46 -0700 Subject: [PATCH 05/21] Update umd link --- content/docs/add-react-to-an-existing-app.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index 015f336b898..2655c7d1481 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -19,11 +19,11 @@ In some cases, [more parts of the page become driven by React over time](https:/ ```html ``` From 90de4692282b904ee0862c85cd137d9dd38e7e95 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Sat, 23 Jun 2018 10:59:54 -0700 Subject: [PATCH 06/21] Add prod minification section --- content/docs/add-react-to-an-existing-app.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index 2655c7d1481..7631b840b8d 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -67,3 +67,13 @@ babel --presets=react-app src -d build ```html ``` + +### 5. Production + +You probably already have a minification step for your JavaScript - don't forget to minify your component files too! + +_Change React scripts to production mode_ +``` +https://unpkg.com/react@16/umd/react.production.min.js +https://unpkg.com/react-dom@16/umd/react-dom.production.min.js +``` From 6f84692bafa7228ffb1ed4bc699fb76890b30833 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Sat, 23 Jun 2018 11:09:55 -0700 Subject: [PATCH 07/21] Show "button" example in several targets --- content/docs/add-react-to-an-existing-app.md | 32 +++++++++++++++----- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index 7631b840b8d..48577befb70 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -30,16 +30,33 @@ In some cases, [more parts of the page become driven by React over time](https:/ ### 2. Write your components ```js -// src/widget.js -class Widget extends React.Component { +// src/button.js + +class Button extends React.Component { render() { - return
Hello, world!
; + return ( + + ); } } +``` + +```js +// Render in several places ReactDOM.render( - , - document.querySelector('.widget') + - ); - } -} +### Step 1: Add a DOM Container to the HTML + +First, open the HTML markup of the page where you'd like to use React. Add an empty `
` tag to mark the spot where you want to display something with it. For example: + +```html{3} + + + + + ``` -```js -// Render in several places +We gave this `
` a unique `class` HTML attribute. This will allow us to find it from the JavaScript code later. -ReactDOM.render( - +); ``` + +While **JSX is optional**, most people prefer it after spending some time with React. + + diff --git a/content/docs/nav.yml b/content/docs/nav.yml index 43b5d8e395d..77cb52f2e62 100644 --- a/content/docs/nav.yml +++ b/content/docs/nav.yml @@ -2,10 +2,10 @@ items: - id: try-react title: Try React - - id: add-react-to-a-new-app - title: Add React to a New App - id: add-react-to-an-existing-app - title: Add React to an Existing App + title: Add React to a Website + - id: add-react-to-a-new-app + title: Create a New React App - id: cdn-links title: CDN Links - title: Main Concepts From 74edd2564c8ff00bd3d8822247d4cb36e2005653 Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Mon, 25 Jun 2018 14:17:58 +0100 Subject: [PATCH 09/21] More --- content/docs/add-react-to-an-existing-app.md | 102 +++++++++++-------- 1 file changed, 62 insertions(+), 40 deletions(-) diff --git a/content/docs/add-react-to-an-existing-app.md b/content/docs/add-react-to-an-existing-app.md index a940ede9147..91b69d1814f 100644 --- a/content/docs/add-react-to-an-existing-app.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -10,7 +10,7 @@ Use as little or as much React as you need. 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. -The majority of websites aren't, and don't need to be, [single-page apps](/docs/add-react-to-a-new-app.html). 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](https://www.youtube.com/watch?v=BF58ZJ1ZQxY), or keep it contained to a few dynamic widgets. +The majority of websites aren't, and don't need to be, [single-page apps](/docs/add-react-to-a-new-app.html). 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. ## Add React in One Minute @@ -18,51 +18,51 @@ In this section, we will show how to add a React component to an existing HTML p 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.** -Optional: [Download the full example (2KB zipped)](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605/archive/e719c1eff0f004449c3e3c1c816f9937a184ba83.zip) +Optional: [Download the full example (2KB zipped)](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605/archive/b396eb0333064a2859b6cf27fa6b451f9e4a8c6a.zip) ### Step 1: Add a DOM Container to the HTML -First, open the HTML markup of the page where you'd like to use React. Add an empty `
` tag to mark the spot where you want to display something with it. For example: +First, open the HTML page you want to edit. Add an empty `
` tag to mark the spot where you want to display something with React. For example: ```html{3} - + ``` -We gave this `
` a unique `class` HTML attribute. This will allow us to find it from the JavaScript code later. +We gave this `
` a unique `class` HTML attribute. This will allow us to find it from the JavaScript code later and display a React component inside of it. >Tip > ->This `
` is called a "DOM container" because it will *contain* a React component. It can be placed **anywhere** inside the `` tag. You can 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. +>You can place a "container" `
` like this **anywhere** inside the `` 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. ### Step 2: Add the Script Tags Next, add three ` - + + + + - - + + - - + ``` The first two tags load React. The third one will load your component code. - ### Step 3: Create a React Component -Create a file called `like_button.js` next to your HTML page, and paste [this starter code](https://cdn.rawgit.com/gaearon/0b180827c190fe4fd98b4c7f570ea4a8/raw/a29c36bd29084ac2c3267176db9cd7afd55d399d/LikeButton.js). +Create a file called `like_button.js` next to your HTML page. + +Open this [this starter code](https://cdn.rawgit.com/gaearon/0b180827c190fe4fd98b4c7f570ea4a8/raw/b9157ce933c79a4559d2aa9ff3372668cce48de7/LikeButton.js) and paste it into the file you created. >Tip > @@ -74,48 +74,43 @@ After the starter code, add two lines to the bottom of `like_button.js`: // ... the starter code you pasted ... let domContainer = document.querySelector('.like_button_container'); -ReactDOM.render(React.createElement(LikeButton), domContainer); +ReactDOM.render(e(LikeButton), domContainer); ``` -These two lines of code find the DOM container element, and then display our "Like" button React component inside of it. And that's the end of this section! There is no step four. **You have just added the first React component to your website.** - -**[View the full example source code](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605)** - -**[Download the full example (2KB zipped)](https://gist.github.com/gaearon/6668a1f6986742109c00a581ce704605/archive/e719c1eff0f004449c3e3c1c816f9937a184ba83.zip)** +These two lines of code find the `
` we added to our HTML in the first step, and then display our "Like" button React component inside of it. +### You're Done! -## Development and Production Versions +There is no step four. **You have just added the first React component to your website.** +Check out the next sections for more tips on integrating React. -In both ` - -``` +## Tip: Minify JavaScript for Production -It has many helpful warnings and better error messages, but it's not suitable for production. +Before deploying your website to production, be mindful that unminifed JavaScript can significantly slow down the page for your users. -During deployment, replace `development.js` with `production.min.js` in both tags: +If you already minify the application scripts, all you need to do is to ensure that the deployed HTML loads the versions of React ending in `production.min.js`: -```html +```js ``` -Now you can ship React to your users! - +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). -## Optional: Add JSX +## Optional: Try React with JSX -In the example above, we only relied on features that are natively supported by the browsers. - -This is why we used `React.createElement()` to specify what to display on the screen: +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: ```js +const e = React.createElement; + // Display a "Like" button -return React.createElement( +return e( 'button', { onClick: () => this.setState({ liked: true }) }, 'Like' @@ -125,6 +120,7 @@ return React.createElement( However, React also offers an option to use [JSX](/docs/introducing-jsx.html) instead: ```js +// Display a "Like" button return (