diff --git a/circle.yml b/circle.yml index 3b8e1bb3fa4..ac02ae5704c 100644 --- a/circle.yml +++ b/circle.yml @@ -1,9 +1,4 @@ --- -general: - branches: - ignore: - - gh-pages - machine: timezone: America/Los_Angeles node: diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml index 58e1c03dca6..7b562e2891b 100644 --- a/docs/_data/nav_docs.yml +++ b/docs/_data/nav_docs.yml @@ -30,6 +30,8 @@ items: - id: jsx-in-depth title: JSX In Depth + - id: typechecking-with-proptypes + title: Typechecking With PropTypes - id: refs-and-the-dom title: Refs and the DOM - id: uncontrolled-components @@ -48,6 +50,8 @@ title: Web Components - id: higher-order-components title: Higher-Order Components + - id: integrating-with-other-libraries + title: Integrating with Other Libraries - title: Reference items: - id: react-api diff --git a/docs/_data/nav_tutorial.yml b/docs/_data/nav_tutorial.yml index efa090f0cec..49cc7557f91 100644 --- a/docs/_data/nav_tutorial.yml +++ b/docs/_data/nav_tutorial.yml @@ -1,12 +1,29 @@ - title: Tutorial items: - id: tutorial - title: Overview + title: Before We Start subitems: - id: what-were-building title: What We're Building href: /react/tutorial/tutorial.html#what-were-building forceInternal: true + - id: prerequisites + title: Prerequisites + href: /react/tutorial/tutorial.html#prerequisites + forceInternal: true + - id: how-to-follow-along + title: How to Follow Along + href: /react/tutorial/tutorial.html#how-to-follow-along + forceInternal: true + - id: help-im-stuck + title: Help, I'm Stuck! + href: /react/tutorial/tutorial.html#help-im-stuck + forceInternal: true + - id: overview + title: Overview + href: /react/tutorial/tutorial.html#overview + forceInternal: true + subitems: - id: what-is-react title: What is React? href: /react/tutorial/tutorial.html#what-is-react diff --git a/docs/_js/live_editor.js b/docs/_js/live_editor.js index 134cae5b86b..9f1952aeb6b 100644 --- a/docs/_js/live_editor.js +++ b/docs/_js/live_editor.js @@ -221,7 +221,7 @@ var ReactPlayground = React.createClass({ } catch (err) { this.setTimeout(function() { ReactDOM.render( -
{err.toString()}
, +
{err.toString()}
, mountNode ); }, 500); diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 1819afec42c..40c1a0a74f7 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -35,18 +35,18 @@ - - - - - - - - + + + + + + + + diff --git a/docs/circle.yml b/docs/circle.yml new file mode 100644 index 00000000000..774c6cec668 --- /dev/null +++ b/docs/circle.yml @@ -0,0 +1,5 @@ +--- +general: + branches: + ignore: + - gh-pages diff --git a/docs/community/conferences.md b/docs/community/conferences.md index f16f7650a59..fdb7fdb25f8 100644 --- a/docs/community/conferences.md +++ b/docs/community/conferences.md @@ -14,16 +14,16 @@ March 28th at the [QEII Centre, London](http://qeiicentre.london/) [Website](http://react.london/) -### ReactEurope 2017 -May 18th & 19th in Paris, France - -[Website](http://www.react-europe.org/) - [Schedule](http://www.react-europe.org/#schedule) - ### React Amsterdam 2017 April 21st in Amsterdam, The Netherlands [Website](https://react.amsterdam) - [Twitter](https://twitter.com/reactamsterdam) +### ReactEurope 2017 +May 18th & 19th in Paris, France + +[Website](http://www.react-europe.org/) - [Schedule](http://www.react-europe.org/#schedule) + ### Chain React 2017 July 10-11 in Portland, Oregon USA @@ -34,6 +34,11 @@ August 24-25 in Salt Lake City, Utah USA [Website](http://www.reactrally.com) - [Twitter](https://twitter.com/reactrally) +### React Native EU 2017 +September 6-7 in Wroclaw, Poland + +[Website](http://react-native.eu/) + ### ReactJS Day 2017 October 6th in Verona, Italy @@ -44,11 +49,6 @@ October 13 in Stockholm, Sweden [Website](https://statejs.com/) -### React Native EU 2017 -September 6-7 in Wroclaw, Poland - -[Website](http://react-native.eu/) - ## Past Conferences diff --git a/docs/contributing/codebase-overview.md b/docs/contributing/codebase-overview.md index 637c4893241..22b2a96f187 100644 --- a/docs/contributing/codebase-overview.md +++ b/docs/contributing/codebase-overview.md @@ -38,7 +38,7 @@ var setInnerHTML = require('setInnerHTML'); Haste was originally developed for giant apps like Facebook. It's easy to move files to different folders and import them without worrying about relative paths. The fuzzy file search in any editor always takes you to the correct place thanks to globally unique names. -React itself was extracted from the Facebook codebase and uses Haste for historical reasons. In the future, we will probably [migrate React to use CommonJS or ES Modules](https://github.com/facebook/react/issues/6336) to be more aligned with the community. However, this requires changes in Facebook internal infrastructure so it is unlikely to happen very soon. +React itself was extracted from Facebook's codebase and uses Haste for historical reasons. In the future, we will probably [migrate React to use CommonJS or ES Modules](https://github.com/facebook/react/issues/6336) to be more aligned with the community. However, this requires changes in Facebook's internal infrastructure so it is unlikely to happen very soon. **Haste will make more sense to you if you remember a few rules:** @@ -66,6 +66,7 @@ After cloning the [React repository](https://github.com/facebook/react), you wil * [`src`](https://github.com/facebook/react/tree/master/src) is the source code of React. **If your change is related to the code, `src` is where you'll spend most of your time.** * [`docs`](https://github.com/facebook/react/tree/master/docs) is the React documentation website. When you change APIs, make sure to update the relevant Markdown files. +* [`fixtures`](https://github.com/facebook/react/tree/master/fixtures) contains a few small React test applications for contributors. * [`packages`](https://github.com/facebook/react/tree/master/packages) contains metadata (such as `package.json`) for all packages in the React repository. Nevertheless, their source code is still located inside [`src`](https://github.com/facebook/react/tree/master/src). * `build` is the build output of React. It is not in the repository but it will appear in your React clone after you [build it](/react/contributing/how-to-contribute.html#development-workflow) for the first time. @@ -223,7 +224,7 @@ module.exports = ReactDOMComponent; The `Mixin` in this code has no relation to React `mixins` feature. It is just a way of grouping a few methods under an object. Those methods may later get attached to some other class. We use this pattern in a few places although we try to avoid it in the new code. -Equivalent code in ES6 would look like this: +The equivalent code in ES6 would look like this: ```js class ReactDOMComponent { @@ -301,10 +302,8 @@ While the code is separated in the source tree, the exact package boundaries are The "core" of React includes all the [top-level `React` APIs](/react/docs/top-level-api.html#react), for example: * `React.createElement()` -* `React.createClass()` * `React.Component` * `React.Children` -* `React.PropTypes` **React core only includes the APIs necessary to define components.** It does not include the [reconciliation](/react/docs/reconciliation.html) algorithm or any platform-specific code. It is used both by React DOM and React Native components. diff --git a/docs/contributing/how-to-contribute.md b/docs/contributing/how-to-contribute.md index 5b2c6c50311..3403ca379e4 100644 --- a/docs/contributing/how-to-contribute.md +++ b/docs/contributing/how-to-contribute.md @@ -39,7 +39,7 @@ We are using [GitHub Issues](https://github.com/facebook/react/issues) for our p #### Reporting New Issues -The best way to get your bug fixed is to provide a reduced test case. This [JSFiddle template](https://jsfiddle.net/reactjs/69z2wepo/) is a great starting point. +The best way to get your bug fixed is to provide a reduced test case. This [JSFiddle template](https://jsfiddle.net/84v837e9/) is a great starting point. #### Security Bugs @@ -64,7 +64,7 @@ Working on your first Pull Request? You can learn how from this free video serie **[How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)** -To help you get your feet wet and get you familiar with our contribution process, we have a list of **[good first bugs](https://github.com/facebook/react/labels/good%20first%20bug)** that contain bugs which are fairly easy to fix. This is a great place to get started. +To help you get your feet wet and get you familiar with our contribution process, we have a list of **[beginner friendly issues](https://github.com/facebook/react/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+beginner%22)** that contain bugs which are fairly easy to fix. This is a great place to get started. If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don't accidentally duplicate your effort. @@ -101,7 +101,7 @@ In order to accept your pull request, we need you to submit a CLA. You only need ### Development Workflow -After cloning React, run `npm install` to fetch its dependencies. +After cloning React, run `npm install` to fetch its dependencies. Then, you can run several commands: * `npm run lint` checks the code style. diff --git a/docs/docs/installation.md b/docs/docs/installation.md index d4ee06ae544..bbbaf4cadc2 100644 --- a/docs/docs/installation.md +++ b/docs/docs/installation.md @@ -11,27 +11,128 @@ redirect_from: - "docs/environments.html" next: hello-world.html --- + React is flexible and can be used in 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. +
+ + + Which of these options best describes what you want to do? +
+
+ +
+ + + ## Trying Out React If you're just interested in playing around with React, you can use CodePen. Try starting from [this Hello World example code](http://codepen.io/gaearon/pen/rrpgNB?editors=0010). You don't need to install anything; you can just modify the code and see if it works. If you prefer to use your own text editor, you can also download this HTML file, edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production. -## Creating a Single Page Application +If you want to use it for a full application, there are two popular ways to get started with React: using Create React App, or adding it to an existing application. + + + +## Creating a New Application [Create React App](http://github.com/facebookincubator/create-react-app) is the best way to start building a new React single page application. It sets up your development environment so that you can use the latest JavaScript features, provides a nice developer experience, and optimizes your app for production. ```bash npm install -g create-react-app -create-react-app hello-world -cd hello-world +create-react-app my-app + +cd my-app 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. It uses [webpack](https://webpack.js.org/), [Babel](http://babeljs.io/) and [ESLint](http://eslint.org/) under the hood, but configures them for you. +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 build tools like Babel and webpack under the hood, but works with zero configuration. + +When you're ready to deploy to production, running `npm run build` will create an optimized build of your app in the `build` folder. You can learn more about Create React App [from its README](https://github.com/facebookincubator/create-react-app#create-react-app-) and the [User Guide](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#table-of-contents). + + ## Adding React to an Existing Application @@ -103,10 +204,6 @@ To create an optimized production build with Brunch, just add the `-p` flag to t 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. -#### Create React App - -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. - #### Rollup Use [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace) plugin together with [rollup-plugin-commonjs](https://github.com/rollup/rollup-plugin-commonjs) (in that order) to remove development-only code. [See this gist](https://gist.github.com/Rich-Harris/cb14f4bc0670c47d00d191565be36bf0) for a complete setup example. @@ -134,3 +231,96 @@ The versions above are only meant for development, and are not suitable for prod To load a specific version of `react` and `react-dom`, replace `15` with the version number. If you use Bower, React is available via the `react` package. + + diff --git a/docs/docs/integrating-with-other-libraries.md b/docs/docs/integrating-with-other-libraries.md new file mode 100644 index 00000000000..4f393a9710c --- /dev/null +++ b/docs/docs/integrating-with-other-libraries.md @@ -0,0 +1,439 @@ +--- +id: integrating-with-other-libraries +title: Integrating with Other Libraries +permalink: docs/integrating-with-other-libraries.html +--- + +React can be used in any web application. It can be embedded in other applications and, with a little care, other applications can be embedded in React. This guide will examine some of the more common use cases, focusing on integration with [jQuery](https://jquery.com/) and [Backbone](http://backbonejs.org/), but the same ideas can be applied to integrating components with any existing code. + +## Integrating with DOM Manipulation Plugins + +React is unaware of changes made to the DOM outside of React. It determines updates based on its own internal representation, and if the same DOM nodes are manipulated by another library, React gets confused and has no way to recover. + +This does not mean it is impossible or even necessarily difficult to combine React with other ways of affecting the DOM, you just have to be mindful of what each are doing. + +The easiest way to avoid conflicts is to prevent the React component from updating. You can do this by rendering elements that React has no reason to update, like an empty `
`. + +### How to Approach the Problem + +To demonstrate this, let's sketch out a wrapper for a generic jQuery plugin. + +We will attach a [ref](/react/docs/refs-and-the-dom.html) to the root DOM element. Inside `componentDidMount`, we will get a reference to it so we can pass it to the jQuery plugin. + +To prevent React from touching the DOM after mounting, we will return an empty `
` from the `render()` method. The `
` element has no properties or children, so React has no reason to update it, leaving the jQuery plugin free to manage that part of the DOM: + +```js{3,4,8,12} +class SomePlugin extends React.Component { + componentDidMount() { + this.$el = $(this.el); + this.$el.somePlugin(); + } + + componentWillUnmount() { + this.$el.somePlugin('destroy'); + } + + render() { + return
this.el = el} />; + } +} +``` + +Note that we defined both `componentDidMount` and `componentWillUnmount` [lifecycle hooks](/react/docs/react-component.html#the-component-lifecycle). Many jQuery plugins attach event listeners to the DOM so it's important to detach them in `componentWillUnmount`. If the plugin does not provide a method for cleanup, you will probably have to provide your own, remembering to remove any event listeners the plugin registered to prevent memory leaks. + +### Integrating with jQuery Chosen Plugin + +For a more concrete example of these concepts, let's write a minimal wrapper for the plugin [Chosen](https://harvesthq.github.io/chosen/), which augments `` DOM node, it reads the attributes off of the original DOM node, hides it with an inline style, and then appends a separate DOM node with its own visual representation right after the `` wrapped in a `
`: + +```js{4,5} +class Chosen extends React.Component { + render() { + return ( +
+ +
+ ); + } +} +``` + +Notice how we wrapped `` node we passed to it. However, as far as React is concerned, `
` always only has a single child. This is how we ensure that React updates won't conflict with the extra DOM node appended by Chosen. It is important that if you modify the DOM outside of React flow, you must ensure React doesn't have a reason to touch those DOM nodes. + +Next, we will implement the lifecycle hooks. We need to initialize Chosen with the ref to the ` this.el = el}> +``` + +This is enough to get our component to render, but we also want to be notified about the value changes. To do this, we will subscribe to the jQuery `change` event on the ``, but we will also add a `componentDidUpdate()` lifecycle hook that notifies Chosen about changes in the children list: + +```js{2,3} +componentDidUpdate(prevProps) { + if (prevProps.children !== this.props.children) { + this.$el.trigger("chosen:updated"); + } +} +``` + +This way, Chosen will know to update its DOM element when the ` this.el = el}> + {this.props.children} + +
+ ); + } +} +``` + +[Try it on CodePen.](http://codepen.io/gaearon/pen/xdgKOz?editors=0010) + +## Integrating with Other View Libraries + +React can be embedded into other applications thanks to the flexibility of [`ReactDOM.render()`](/react/docs/react-dom.html#render). + +Although React is commonly used at startup to load a single root React component into the DOM, `ReactDOM.render()` can also be called multiple times for independent parts of the UI which can be as small as a button, or as large as an app. + +In fact, this is exactly how React is used at Facebook. This lets us write applications in React piece by piece, and combine it with our existing server-generated templates and other client-side code. + +### Replacing String-Based Rendering with React + +A common pattern in older web applications is to describe chunks of the DOM as a string and insert it into the DOM like so: `$el.html(htmlString)`. These points in a codebase are perfect for introducing React. Just rewrite the string based rendering as a React component. + +So the following jQuery implementation... + +```js +$('#container').html(''); +$('#btn').click(function() { + alert('Hello!'); +}); +``` + +...could be rewritten using a React component: + +```js +function Button() { + return ; +} + +ReactDOM.render( + ; +} + +function HelloButton() { + function handleClick() { + alert('Hello!'); + } + return