diff --git a/.babelrc b/.babelrc index cda595ba65281..68a8716985e67 100644 --- a/.babelrc +++ b/.babelrc @@ -19,10 +19,7 @@ "transform-es2015-parameters", ["transform-es2015-destructuring", { "loose": true }], ["transform-es2015-block-scoping", { "throwIfClosureRequired": true }], - "transform-es2015-modules-commonjs", "transform-es3-member-expression-literals", - "transform-es3-property-literals", - "./scripts/babel/transform-object-assign-require", - "transform-react-jsx-source" + "transform-es3-property-literals" ] } diff --git a/.eslintignore b/.eslintignore index 225671653384a..c9866f87df26b 100644 --- a/.eslintignore +++ b/.eslintignore @@ -9,7 +9,6 @@ docs/_site/ docs/vendor/bundle/ # This should be more like examples/**/thirdparty/** but # we should fix https://github.com/facebook/esprima/pull/85 first -examples/ fixtures/ # Ignore built files. build/ diff --git a/.flowconfig b/.flowconfig index 4c85601032784..2eea16d57788c 100644 --- a/.flowconfig +++ b/.flowconfig @@ -1,8 +1,8 @@ [ignore] -/examples/.* /fixtures/.* /build/.* +/scripts/.* /.*/node_modules/y18n/.* /.*/__mocks__/.* /.*/__tests__/.* diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 4921e268ff53b..31ac431253519 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -2,7 +2,7 @@ **What is the current behavior?** -**If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://jsfiddle.net or similar (template: https://jsfiddle.net/reactjs/69z2wepo/).** +**If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://jsfiddle.net or similar (template: https://jsfiddle.net/84v837e9/).** **What is the expected behavior?** diff --git a/.gitignore b/.gitignore index 18dfb23662d25..8864c101120a9 100644 --- a/.gitignore +++ b/.gitignore @@ -17,8 +17,6 @@ docs/.sass-cache docs/js/* docs/downloads/*.zip docs/vendor/bundle -examples/shared/*.js -examples/**/bundle.js fixtures/dom/public/react-dom.js fixtures/dom/public/react.js test/the-files-to-test.generated.js @@ -29,3 +27,5 @@ chrome-user-data .idea *.iml .vscode +*.swp +*.swo diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ce56e7e77896..3765106bc4ccc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,31 @@ +## 15.5.0 (April 7, 2017) + +### React + +* Added a deprecation warning for `React.createClass`. Points users to create-react-class instead. ([@acdlite](https://github.com/acdlite) in [d9a4fa4](https://github.com/facebook/react/commit/d9a4fa4f51c6da895e1655f32255cf72c0fe620e)) +* Added a deprecation warning for `React.PropTypes`. Points users to prop-types instead. ([@acdlite](https://github.com/acdlite) in [043845c](https://github.com/facebook/react/commit/043845ce75ea0812286bbbd9d34994bb7e01eb28)) +* Fixed an issue when using `ReactDOM` together with `ReactDOMServer`. ([@wacii](https://github.com/wacii) in [#9005](https://github.com/facebook/react/pull/9005)) +* Fixed issue with Closure Compiler. ([@anmonteiro](https://github.com/anmonteiro) in [#8895](https://github.com/facebook/react/pull/8895)) +* Another fix for Closure Compiler. ([@Shastel](https://github.com/Shastel) in [#8882](https://github.com/facebook/react/pull/8882)) +* Added component stack info to invalid element type warning. ([@n3tr](https://github.com/n3tr) in [#8495](https://github.com/facebook/react/pull/8495)) + +### React DOM + +* Fixed Chrome bug when backspacing in number inputs. ([@nhunzaker](https://github.com/nhunzaker) in [#7359](https://github.com/facebook/react/pull/7359)) +* Added `react-dom/test-utils`, which exports the React Test Utils. ([@bvaughn](https://github.com/bvaughn)) + +### React Test Renderer + +* Fixed bug where `componentWillUnmount` was not called for children. ([@gre](https://github.com/gre) in [#8512](https://github.com/facebook/react/pull/8512)) +* Added `react-test-renderer/shallow`, which exports the shallow renderer. ([@bvaughn](https://github.com/bvaughn)) + +### React Addons + +* Last release for addons; they will no longer be actively maintained. +* Removed `peerDependencies` so that addons continue to work indefinitely. ([@acdlite](https://github.com/acdlite) and [@bvaughn](https://github.com/bvaughn) in [8a06cd7](https://github.com/facebook/react/commit/8a06cd7a786822fce229197cac8125a551e8abfa) and [67a8db3](https://github.com/facebook/react/commit/67a8db3650d724a51e70be130e9008806402678a)) +* Updated to remove references to `React.createClass` and `React.PropTypes` ([@acdlite](https://github.com/acdlite) in [12a96b9](https://github.com/facebook/react/commit/12a96b94823d6b6de6b1ac13bd576864abd50175)) +* `react-addons-test-utils` is deprecated. Use `react-dom/test-utils` and `react-test-renderer/shallow` instead. ([@bvaughn](https://github.com/bvaughn)) + ## 15.4.2 (January 6, 2017) ### React diff --git a/Gruntfile.js b/Gruntfile.js deleted file mode 100644 index 58c832e29c87d..0000000000000 --- a/Gruntfile.js +++ /dev/null @@ -1,202 +0,0 @@ -'use strict'; - -var path = require('path'); - -var GULP_EXE = 'gulp'; -if (process.platform === 'win32') { - GULP_EXE += '.cmd'; -} - -module.exports = function(grunt) { - - grunt.initConfig({ - pkg: grunt.file.readJSON('package.json'), - browserify: require('./grunt/config/browserify'), - npm: require('./grunt/config/npm'), - clean: [ - './build', - './*.gem', - './docs/_site', - './examples/shared/*.js', - '.module-cache', - ], - 'compare_size': require('./grunt/config/compare_size'), - }); - - function spawnGulp(args, opts, done) { - - grunt.util.spawn({ - // This could be more flexible (require.resolve & lookup bin in package) - // but if it breaks we'll fix it then. - cmd: path.join('node_modules', '.bin', GULP_EXE), - args: args, - opts: Object.assign({stdio: 'inherit'}, opts), - }, function(err, result, code) { - if (err) { - grunt.fail.fatal('Something went wrong running gulp: ', result); - } - done(code === 0); - }); - } - - Object.keys(grunt.file.readJSON('package.json').devDependencies) - .filter(function(npmTaskName) { - return npmTaskName.indexOf('grunt-') === 0; - }) - .filter(function(npmTaskName) { - return npmTaskName !== 'grunt-cli'; - }) - .forEach(function(npmTaskName) { - grunt.loadNpmTasks(npmTaskName); - }); - - grunt.registerTask('eslint', function() { - // Use gulp here. - spawnGulp(['eslint'], null, this.async()); - }); - - grunt.registerTask('lint', ['eslint']); - - grunt.registerTask('flow', function() { - // Use gulp here. - spawnGulp(['flow'], null, this.async()); - }); - - grunt.registerTask('delete-build-modules', function() { - // Use gulp here. - spawnGulp(['react:clean'], null, this.async()); - }); - - // Our own browserify-based tasks to build a single JS file build. - grunt.registerMultiTask('browserify', require('./grunt/tasks/browserify')); - - grunt.registerMultiTask('npm', require('./grunt/tasks/npm')); - - var npmReactTasks = require('./grunt/tasks/npm-react'); - grunt.registerTask('npm-react:release', npmReactTasks.buildRelease); - grunt.registerTask('npm-react:pack', npmReactTasks.packRelease); - - var npmReactDOMTasks = require('./grunt/tasks/npm-react-dom'); - grunt.registerTask('npm-react-dom:release', npmReactDOMTasks.buildRelease); - grunt.registerTask('npm-react-dom:pack', npmReactDOMTasks.packRelease); - - var npmReactNativeTasks = require('./grunt/tasks/npm-react-native'); - grunt.registerTask('npm-react-native:release', npmReactNativeTasks.buildRelease); - grunt.registerTask('npm-react-native:pack', npmReactNativeTasks.packRelease); - - var npmReactTestRendererTasks = require('./grunt/tasks/npm-react-test'); - grunt.registerTask('npm-react-test:release', npmReactTestRendererTasks.buildRelease); - grunt.registerTask('npm-react-test:pack', npmReactTestRendererTasks.packRelease); - - var npmReactNoopRendererTasks = require('./grunt/tasks/npm-react-noop'); - grunt.registerTask('npm-react-noop:release', npmReactNoopRendererTasks.buildRelease); - grunt.registerTask('npm-react-noop:pack', npmReactNoopRendererTasks.packRelease); - - grunt.registerTask('version-check', function() { - // Use gulp here. - spawnGulp(['version-check'], null, this.async()); - }); - - grunt.registerTask('build:basic', [ - 'build-modules', - 'version-check', - 'browserify:basic', - ]); - grunt.registerTask('build:min', [ - 'build-modules', - 'version-check', - 'browserify:min', - ]); - grunt.registerTask('build:dom', [ - 'build-modules', - 'version-check', - 'browserify:dom', - ]); - grunt.registerTask('build:dom-min', [ - 'build-modules', - 'version-check', - 'browserify:domMin', - ]); - grunt.registerTask('build:dom-server', [ - 'build-modules', - 'version-check', - 'browserify:domServer', - ]); - grunt.registerTask('build:dom-server-min', [ - 'build-modules', - 'version-check', - 'browserify:domServerMin', - ]); - grunt.registerTask('build:dom-fiber', [ - 'build-modules', - 'version-check', - 'browserify:domFiber', - ]); - grunt.registerTask('build:dom-fiber-min', [ - 'build-modules', - 'version-check', - 'browserify:domFiberMin', - ]); - grunt.registerTask('build:npm-react', [ - 'version-check', - 'build-modules', - 'npm-react:release', - ]); - - var jestTasks = require('./grunt/tasks/jest'); - grunt.registerTask('jest:normal', jestTasks.normal); - grunt.registerTask('jest:coverage', jestTasks.coverage); - - grunt.registerTask('test', ['jest:normal']); - grunt.registerTask('npm:test', ['build', 'npm:pack']); - - // Optimized build task that does all of our builds. The subtasks will be run - // in order so we can take advantage of that and only run build-modules once. - grunt.registerTask('build', [ - 'delete-build-modules', - 'build-modules', - 'version-check', - 'browserify:basic', - 'browserify:min', - 'browserify:dom', - 'browserify:domMin', - 'browserify:domServer', - 'browserify:domServerMin', - 'browserify:domFiber', - 'browserify:domFiberMin', - 'npm-react:release', - 'npm-react:pack', - 'npm-react-dom:release', - 'npm-react-dom:pack', - 'npm-react-native:release', - 'npm-react-native:pack', - 'npm-react-test:release', - 'npm-react-test:pack', - 'npm-react-noop:release', - 'npm-react-noop:pack', - 'compare_size', - ]); - - // Automate the release! - var releaseTasks = require('./grunt/tasks/release'); - grunt.registerTask('release:setup', releaseTasks.setup); - grunt.registerTask('release:bower', releaseTasks.bower); - grunt.registerTask('release:docs', releaseTasks.docs); - grunt.registerTask('release:msg', releaseTasks.msg); - - grunt.registerTask('release', [ - 'release:setup', - 'clean', - 'build', - 'release:bower', - 'release:docs', - 'release:msg', - ]); - - grunt.registerTask('build-modules', function() { - spawnGulp(['react:modules'], null, this.async()); - }); - - // The default task - build - to keep setup easy. - grunt.registerTask('default', ['build']); -}; diff --git a/README.md b/README.md index df717360fee9a..2ae261c6994a9 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ React is flexible and can be used in a variety of projects. You can create new a The recommended way to install React depends on your project. Here you can find short guides for the most common scenarios: * [Trying Out React](https://facebook.github.io/react/docs/installation.html#trying-out-react) -* [Creating a Single Page Application](https://facebook.github.io/react/docs/installation.html#creating-a-single-page-application) +* [Creating a New Application](https://facebook.github.io/react/docs/installation.html#creating-a-new-application) * [Adding React to an Existing Application](https://facebook.github.io/react/docs/installation.html#adding-react-to-an-existing-application) ## Contributing @@ -53,9 +53,9 @@ Facebook has adopted a Code of Conduct that we expect project participants to ad Read our [contributing guide](https://facebook.github.io/react/contributing/how-to-contribute.html) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to React. -### Good First Bug +### Beginner Friendly Bugs -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 bugs](https://github.com/facebook/react/labels/Difficulty%3A%20beginner) that contain bugs which are fairly easy to fix. This is a great place to get started. ### License diff --git a/circle.yml b/circle.yml index ef3dca19875bc..aa793704867a3 100644 --- a/circle.yml +++ b/circle.yml @@ -33,7 +33,6 @@ dependencies: # - npm ls --depth=0 cache_directories: - docs/vendor/bundle - - .grunt # Show size comparisons between builds - ~/react-gh-pages # docs checkout - ~/.yarn - ~/.yarn-cache diff --git a/docs/_data/authors.yml b/docs/_data/authors.yml index eff00b7e2eb59..d52ee1d96d528 100644 --- a/docs/_data/authors.yml +++ b/docs/_data/authors.yml @@ -1,6 +1,9 @@ # Map of short name to more information. `name` will be used but if you don't # want to use your real name, just use whatever. If url is included, your name # will be a link to the provided url. +acdlite: + name: Andrew Clark + url: https://twitter.com/acdlite benigeri: name: Paul Benigeri url: https://github.com/benigeri diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml index 1e66741d1fb24..58e1c03dca649 100644 --- a/docs/_data/nav_docs.yml +++ b/docs/_data/nav_docs.yml @@ -30,8 +30,6 @@ 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 @@ -65,22 +63,3 @@ title: DOM Elements - id: events title: SyntheticEvent - - id: addons - title: Add-Ons - subitems: - - id: perf - title: Performance Tools - - id: test-utils - title: Test Utilities - - id: animation - title: Animation - - id: create-fragment - title: Keyed Fragments - - id: update - title: Immutability Helpers - - id: pure-render-mixin - title: PureRenderMixin - - id: shallow-compare - title: Shallow Compare - - id: two-way-binding-helpers - title: Two-way Binding Helpers diff --git a/docs/_data/nav_tutorial.yml b/docs/_data/nav_tutorial.yml index efa090f0cecb1..49cc7557f911e 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/_posts/2017-04-07-react-v15.5.0.md b/docs/_posts/2017-04-07-react-v15.5.0.md new file mode 100644 index 0000000000000..7c38475c1a483 --- /dev/null +++ b/docs/_posts/2017-04-07-react-v15.5.0.md @@ -0,0 +1,227 @@ +--- +title: "React v15.5.0" +author: acdlite +--- + +It's been exactly one year since the last breaking change to React. Our next major release, React 16, will include some exciting improvements, including a [complete rewrite](https://www.youtube.com/watch?v=ZCuYPiUIONs) of React's internals. [We take stability seriously](/react/contributing/design-principles.html#stability), and are committed to bringing those improvements to all of our users with minimal effort. + +To that end, today we're releasing React 15.5.0. + +### New Deprecation Warnings + +The biggest change is that we've extracted `React.PropTypes` and `React.createClass` into their own packages. Both are still accessible via the main `React` object, but using either will log a one-time deprecation warning to the console when in development mode. This will enable future code size optimizations. + +These warnings will not affect the behavior of your application. However, we realize they may cause some frustration, particularly if you use a testing framework that treats `console.error` as a failure. + +**Adding new warnings is not something we do lightly.** Warnings in React are not mere suggestions — they are integral to our strategy of keeping as many people as possible on the latest version of React. We never add warnings without providing an incremental path forward. + +So while the warnings may cause frustration in the short-term, we believe **prodding developers to migrate their codebases now prevents greater frustration in the future**. Proactively fixing warnings ensures you are prepared for the next major release. If your app produces zero warnings in 15.5, it should continue to work in 16 without any changes. + +For each of these new deprecations, we've provided a codemod to automatically migrate your code. They are available as part of the [react-codemod](https://github.com/reactjs/react-codemod) project. + +### Migrating from React.PropTypes + +Prop types are a feature for runtime validation of props during development. We've extracted the built-in prop types to a separate package to reflect the fact that not everybody uses them. + +In 15.5, instead of accessing `PropTypes` from the main `React` object, install the `prop-types` package and import them from there: + +```js{11,16,25} +// Before (15.4 and below) +import React from 'react'; + +class Component extends React.Component { + render() { + return
{this.props.text}
; + } +} + +Component.propTypes = { + text: React.PropTypes.string.isRequired, +} + +// After (15.5) +import React from 'react'; +import PropTypes from 'prop-types'; + +class Component extends React.Component { + render() { + return
{this.props.text}
; + } +} + +Component.propTypes = { + text: PropTypes.string.isRequired, +}; +``` + +The [codemod](https://github.com/reactjs/react-codemod#react-proptypes-to-prop-types) for this change performs this conversion automatically. Basic usage: + +```bash +jscodeshift -t react-codemod/transforms/React-PropTypes-to-prop-types.js +``` + + +The `propTypes`, `contextTypes`, and `childContextTypes` APIs will work exactly as before. The only change is that the built-in validators now live in a separate package. + +You may also consider using [Flow](https://flow.org/) to statically type check your JavaScript code, including [React components](https://flow.org/en/docs/frameworks/react/#setup-flow-with-react-a-classtoc-idtoc-setup-flow-with-react-hreftoc-setup-flow-with-reacta). + +### Migrating from React.createClass + +When React was initially released, there was no idiomatic way to create classes in JavaScript, so we provided our own: `React.createClass`. + +Later, classes were added to the language as part of ES2015, so we added the ability to create React components using JavaScript classes. **Along with functional components, JavaScript classes are now the [preferred way to create components in React](/react/docs/components-and-props.html#functional-and-class-components).** + +For your existing `createClass` components, we recommend that you migrate them to JavaScript classes. However, if you have components that rely on mixins, converting to classes may not be immediately feasible. If so, `create-react-class` is available on npm as a drop-in replacement: + +```js{4,13,15} +// Before (15.4 and below) +var React = require('react'); + +var Component = React.createClass({ + mixins: [MixinA], + render() { + return ; + } +}); + +// After (15.5) +var React = require('react'); +var createReactClass = require('create-react-class'); + +var Component = createReactClass({ + mixins: [MixinA], + render() { + return ; + } +}); +``` + +Your components will continue to work the same as they did before. + +The [codemod](https://github.com/reactjs/react-codemod#explanation-of-the-new-es2015-class-transform-with-property-initializers) for this change attempts to convert a `createClass` component to a JavaScript class, with a fallback to `create-react-class` if necessary. It has converted thousands of components internally at Facebook. + +Basic usage: + +```bash +jscodeshift -t react-codemod/transforms/class.js path/to/components +``` + +### Discontinuing support for React Addons + +We're discontinuing active maintenance of React Addons packages. In truth, most of these packages haven't been actively maintained in a long time. They will continue to work indefinitely, but we recommend migrating away as soon as you can to prevent future breakages. + +- **react-addons-create-fragment** – React 16 will have first-class support for fragments, at which point this package won't be necessary. We recommend using arrays of keyed elements instead. +- **react-addons-css-transition-group** - Use [react-transition-group/CSSTransitionGroup](https://github.com/reactjs/react-transition-group) instead. Version 1.1.1 provides a drop-in replacement. +- **react-addons-linked-state-mixin** - Explicitly set the `value` and `onChange` handler instead. +- **react-addons-pure-render-mixin** - Use [`React.PureComponent`](/react/docs/react-api.html#react.purecomponent) instead. +- **react-addons-shallow-compare** - Use [`React.PureComponent`](/react/docs/react-api.html#react.purecomponent) instead. +- **react-addons-transition-group** - Use [react-transition-group/TransitionGroup](https://github.com/reactjs/react-transition-group) instead. Version 1.1.1 provides a drop-in replacement. +- **react-addons-update** - Use [immutability-helper](https://github.com/kolodny/immutability-helper) instead, a drop-in replacement. +- **react-linked-input** - Explicitly set the `value` and `onChange` handler instead. + +We're also discontinuing support for the `react-with-addons` UMD build. It will be removed in React 16. + +### React Test Utils + +Currently, the React Test Utils live inside `react-addons-test-utils`. As of 15.5, we're deprecating that package and moving them to `react-dom/test-utils` instead: + +```js +// Before (15.4 and below) +import TestUtils from 'react-addons-test-utils'; + +// After (15.5) +import TestUtils from 'react-dom/test-utils'; +``` + +This reflects the fact that what we call the Test Utils are really a set of APIs that wrap the DOM renderer. + +The exception is shallow rendering, which is not DOM-specific. The shallow renderer has been moved to `react-test-renderer/shallow`. + +```js{2,5} +// Before (15.4 and below) +import { createRenderer } from 'react-addons-test-utils'; + +// After (15.5) +import { createRenderer } from 'react-test-renderer/shallow'; +``` + +--- + +## Acknowledgements + +A special thank you to these folks for transferring ownership of npm package names: + +- [Jason Miller](https://github.com/developit) +- [Aaron Ackerman](https://github.com/aackerman) +- [Vinicius Marson](https://github.com/viniciusmarson) + +--- + +## Installation + +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 add react@^15.5.0 react-dom@^15.5.0 +``` + +To install React with npm, run: + +```bash +npm install --save react@^15.5.0 react-dom@^15.5.0 +``` + +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. + +Remember that by default, React runs extra checks and provides helpful warnings in development mode. When deploying your app, make sure to [compile it in production mode](/react/docs/installation.html#development-and-production-versions). + +In case you don't use a bundler, we also provide pre-built bundles in the npm packages which you can [include as script tags](/react/docs/installation.html#using-a-cdn) on your page: + +* **React** + Dev build with warnings: [react/dist/react.js](https://unpkg.com/react@15.5.0/dist/react.js) + Minified build for production: [react/dist/react.min.js](https://unpkg.com/react@15.5.0/dist/react.min.js) +* **React with Add-Ons** + Dev build with warnings: [react/dist/react-with-addons.js](https://unpkg.com/react@15.5.0/dist/react-with-addons.js) + Minified build for production: [react/dist/react-with-addons.min.js](https://unpkg.com/react@15.5.0/dist/react-with-addons.min.js) +* **React DOM** (include React in the page before React DOM) + Dev build with warnings: [react-dom/dist/react-dom.js](https://unpkg.com/react-dom@15.5.0/dist/react-dom.js) + Minified build for production: [react-dom/dist/react-dom.min.js](https://unpkg.com/react-dom@15.5.0/dist/react-dom.min.js) +* **React DOM Server** (include React in the page before React DOM Server) + Dev build with warnings: [react-dom/dist/react-dom-server.js](https://unpkg.com/react-dom@15.5.0/dist/react-dom-server.js) + Minified build for production: [react-dom/dist/react-dom-server.min.js](https://unpkg.com/react-dom@15.5.0/dist/react-dom-server.min.js) + +We've also published version `15.5.0` of the `react`, `react-dom`, and addons packages on npm and the `react` package on bower. + +--- + +## Changelog + +## 15.5.0 (April 7, 2017) + +### React + +* Added a deprecation warning for `React.createClass`. Points users to create-react-class instead. ([@acdlite](https://github.com/acdlite) in [d9a4fa4](https://github.com/facebook/react/commit/d9a4fa4f51c6da895e1655f32255cf72c0fe620e)) +* Added a deprecation warning for `React.PropTypes`. Points users to prop-types instead. ([@acdlite](https://github.com/acdlite) in [043845c](https://github.com/facebook/react/commit/043845ce75ea0812286bbbd9d34994bb7e01eb28)) +* Fixed an issue when using `ReactDOM` together with `ReactDOMServer`. ([@wacii](https://github.com/wacii) in [#9005](https://github.com/facebook/react/pull/9005)) +* Fixed issue with Closure Compiler. ([@anmonteiro](https://github.com/anmonteiro) in [#8895](https://github.com/facebook/react/pull/8895)) +* Another fix for Closure Compiler. ([@Shastel](https://github.com/Shastel) in [#8882](https://github.com/facebook/react/pull/8882)) +* Added component stack info to invalid element type warning. ([@n3tr](https://github.com/n3tr) in [#8495](https://github.com/facebook/react/pull/8495)) + +### React DOM + +* Fixed Chrome bug when backspacing in number inputs. ([@nhunzaker](https://github.com/nhunzaker) in [#7359](https://github.com/facebook/react/pull/7359)) +* Added `react-dom/test-utils`, which exports the React Test Utils. ([@bvaughn](https://github.com/bvaughn)) + +### React Test Renderer + +* Fixed bug where `componentWillUnmount` was not called for children. ([@gre](https://github.com/gre) in [#8512](https://github.com/facebook/react/pull/8512)) +* Added `react-test-renderer/shallow`, which exports the shallow renderer. ([@bvaughn](https://github.com/bvaughn)) + +### React Addons + +* Last release for addons; they will no longer be actively maintained. +* Removed `peerDependencies` so that addons continue to work indefinitely. ([@acdlite](https://github.com/acdlite) and [@bvaughn](https://github.com/bvaughn) in [8a06cd7](https://github.com/facebook/react/commit/8a06cd7a786822fce229197cac8125a551e8abfa) and [67a8db3](https://github.com/facebook/react/commit/67a8db3650d724a51e70be130e9008806402678a)) +* Updated to remove references to `React.createClass` and `React.PropTypes` ([@acdlite](https://github.com/acdlite) in [12a96b9](https://github.com/facebook/react/commit/12a96b94823d6b6de6b1ac13bd576864abd50175)) +* `react-addons-test-utils` is deprecated. Use `react-dom/test-utils` and `react-test-renderer/shallow` instead. ([@bvaughn](https://github.com/bvaughn)) diff --git a/docs/community/conferences.md b/docs/community/conferences.md index f16f7650a598a..fdb7fdb25f881 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 d0062cf331b78..f0eea5e65228a 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,7 +66,6 @@ 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. -* [`examples`](https://github.com/facebook/react/tree/master/examples) contains a few small React demos with different build setups. * [`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. @@ -224,7 +223,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 { @@ -302,10 +301,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. @@ -401,12 +398,6 @@ React implements a synthetic event system which is agnostic of the renderers and There is a [video with a deep code dive into it](https://www.youtube.com/watch?v=dRo_egw7tBc) (66 mins). -### Add-ons - -Each of the [React add-ons](/react/docs/addons.html) ships as a separate package on npm with a `react-addons-` prefix. Their source is located in [`src/addons`](https://github.com/facebook/react/tree/master/src/addons) with the exception of [`ReactPerf`](https://github.com/facebook/react/blob/master/src/renderers/shared/ReactPerf.js) and [`ReactTestUtils`](https://github.com/facebook/react/blob/master/src/test/ReactTestUtils.js). - -Additionally, we provide a standalone build called `react-with-addons.js` which includes React core *and* all add-ons exposed on the `addons` field of the `React` global object. - ### What Next? Read the [next section](/react/contributing/implementation-notes.html) to learn about the current implementation of reconciler in more detail. diff --git a/docs/contributing/design-principles.md b/docs/contributing/design-principles.md index 3e848df38cb1f..20bc3dd7b0c22 100644 --- a/docs/contributing/design-principles.md +++ b/docs/contributing/design-principles.md @@ -20,7 +20,7 @@ The key feature of React is composition of components. Components written by dif For example, it should be possible to introduce some local state into a component without changing any of the components using it. Similarly, it should be possible to add some initialization and teardown code to any component when necessary. -There is nothing "bad" about using state or lifecycle hooks in components. Like any powerful features, they should be used in moderation, but we have no intention to remove them. On the contrary, we think they are integral parts of what makes React useful. We might enable [more functional patterns](https://github.com/reactjs/react-future/tree/master/07%20-%20Returning%20State) in the future, but both local state and lifecycle hooks will be a part of that model. +There is nothing "bad" about using state or lifecycle hooks in components. Like any powerful feature, they should be used in moderation, but we have no intention to remove them. On the contrary, we think they are integral parts of what makes React useful. We might enable [more functional patterns](https://github.com/reactjs/react-future/tree/master/07%20-%20Returning%20State) in the future, but both local state and lifecycle hooks will be a part of that model. Components are often described as "just functions" but in our view they need to be more than that to be useful. In React, components describe any composable behavior, and this includes rendering, lifecycle, and state. Some external libraries like [Relay](http://facebook.github.io/relay/) augment components with other responsibilities such as describing data dependencies. It is possible that those ideas might make it back into React too in some form. diff --git a/docs/contributing/how-to-contribute.md b/docs/contributing/how-to-contribute.md index 6613a3c74bf4c..b45eb1798b949 100644 --- a/docs/contributing/how-to-contribute.md +++ b/docs/contributing/how-to-contribute.md @@ -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. @@ -115,9 +115,9 @@ We recommend running `npm test` (or its variations above) to make sure you don't First, run `npm run build`. This will produce pre-built bundles in `build` folder, as well as prepare npm packages inside `build/packages`. -The easiest way to try your changes is to open and modify `examples/basic/index.html`. This file already uses `react.js` from the `build` folder so it will pick up your changes. Please make sure to rollback any unintentional changes in `examples` before sending a pull request. +The easiest way to try your changes is to run `npm run build` and then open `fixtures/packaging/babel-standalone/dev.html`. This file already uses `react.js` from the `build` folder so it will pick up your changes. -If you want to try your changes in your existing React project, you may copy `build/react.js`, `build/react-dom.js`, or any other build products into your app and use them instead of the stable version. If your project uses React from npm, you may delete `react` and `react-dom` in its dependencies and use `npm link` to point them to your local `build` folder: +If you want to try your changes in your existing React project, you may copy `build/dist/react.development.js`, `build/dist/react-dom.development.js`, or any other build products into your app and use them instead of the stable version. If your project uses React from npm, you may delete `react` and `react-dom` in its dependencies and use `npm link` to point them to your local `build` folder: ```sh cd your_project diff --git a/docs/contributing/implementation-notes.md b/docs/contributing/implementation-notes.md index 6fb6ed8310016..2309dd721cc1b 100644 --- a/docs/contributing/implementation-notes.md +++ b/docs/contributing/implementation-notes.md @@ -11,6 +11,8 @@ This section is a collection of implementation notes for the [stack reconciler]( It is very technical and assumes a strong understanding of React public API as well as how it's divided into core, renderers, and the reconciler. If you're not very familiar with the React codebase, read [the codebase overview](/react/contributing/codebase-overview.html) first. +It also assumes an understanding of the [differences between React components, their instances, and elements](/react/blog/2015/12/18/react-components-elements-and-instances.html). + The stack reconciler is powering all the React production code today. It is located in [`src/renderers/shared/stack/reconciler`](https://github.com/facebook/react/tree/master/src/renderers/shared/stack) and is used by both React DOM and React Native. ### Video: Building React from Scratch @@ -875,7 +877,7 @@ This document is simplified compared to the real codebase. There are a few impor * [`ReactCompositeComponent`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactCompositeComponent.js) is the equivalent of `CompositeComponent` in this tutorial. It handles calling user-defined components and maintaining their state. * [`instantiateReactComponent`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/instantiateReactComponent.js) contains the switch that picks the right internal instance class to construct for an element. It is equivalent to `instantiateComponent()` in this tutorial. -* [`ReactReconciler`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactReconciler.js) is a wrapper with `mountComponent`, `receiveComponent()`, and `unmountComponent()` methods. It calls the underlying implementations on the internal instances, but also includes some code around them that is shared by all internal instance implementations. +* [`ReactReconciler`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactReconciler.js) is a wrapper with `mountComponent()`, `receiveComponent()`, and `unmountComponent()` methods. It calls the underlying implementations on the internal instances, but also includes some code around them that is shared by all internal instance implementations. * [`ReactChildReconciler`](https://github.com/facebook/react/blob/83381c1673d14cd16cf747e34c945291e5518a86/src/renderers/shared/stack/reconciler/ReactChildReconciler.js) implements the logic for mounting, updating, and unmounting children according to the `key` of their elements. diff --git a/docs/docs/addons-animation.md b/docs/docs/addons-animation.md index 45cc3e6099624..2dd2884ce66d2 100644 --- a/docs/docs/addons-animation.md +++ b/docs/docs/addons-animation.md @@ -4,14 +4,15 @@ title: Animation Add-Ons permalink: docs/animation.html layout: docs category: Add-Ons -prev: addons.html -next: create-fragment.html redirect_from: - "docs/animation-ja-JP.html" - "docs/animation-ko-KR.html" - "docs/animation-zh-CN.html" --- +>Note: +> `ReactTransitionGroup` and `ReactCSSTransitionGroup` are both deprecated as of React v15.5.0. The recommendation is to use `TransitionGroup` and `CSSTransitionGroup` from ['react-transition-group'](https://github.com/reactjs/react-transition-group) instead. + The [`ReactTransitionGroup`](#low-level-api-reacttransitiongroup) add-on component is a low-level API for animation, and [`ReactCSSTransitionGroup`](#high-level-api-reactcsstransitiongroup) is an add-on component for easily implementing basic CSS animations and transitions. ## High-level API: ReactCSSTransitionGroup @@ -21,9 +22,8 @@ The [`ReactTransitionGroup`](#low-level-api-reacttransitiongroup) add-on compone **Importing** ```javascript -import ReactCSSTransitionGroup from 'react-addons-css-transition-group' // ES6 -var ReactCSSTransitionGroup = require('react-addons-css-transition-group') // ES5 with npm -var ReactCSSTransitionGroup = React.addons.CSSTransitionGroup; // ES5 with react-with-addons.js +import ReactCSSTransitionGroup from 'react-addons-css-transition-group'; // ES6 +var ReactCSSTransitionGroup = require('react-addons-css-transition-group'); // ES5 with npm ``` ```javascript{31-36} @@ -231,7 +231,6 @@ You can disable animating `enter` or `leave` animations if you want. For example ```javascript import ReactTransitionGroup from 'react-addons-transition-group' // ES6 var ReactTransitionGroup = require('react-addons-transition-group') // ES5 with npm -var ReactTransitionGroup = React.addons.TransitionGroup; // ES5 with react-with-addons.js ``` `ReactTransitionGroup` is the basis for animations. When children are declaratively added or removed from it (as in the [example above](#getting-started)), special lifecycle hooks are called on them. diff --git a/docs/docs/addons-create-fragment.md b/docs/docs/addons-create-fragment.md index ec3d0457abbbf..806aa826f825d 100644 --- a/docs/docs/addons-create-fragment.md +++ b/docs/docs/addons-create-fragment.md @@ -4,16 +4,13 @@ title: Keyed Fragments permalink: docs/create-fragment.html layout: docs category: Add-Ons -prev: animation.html -next: perf.html --- **Importing** ```javascript -import createFragment from 'react-addons-create-fragment' // ES6 -var createFragment = require('react-addons-create-fragment') // ES5 with npm -var createFragment = React.addons.createFragment; // ES5 with react-with-addons.js +import createFragment from 'react-addons-create-fragment'; // ES6 +var createFragment = require('react-addons-create-fragment'); // ES5 with npm ``` ## Overview @@ -42,8 +39,8 @@ To solve this problem, you can use the `createFragment` add-on to give keys to t Instead of creating arrays, we write: -```js -import createFragment from 'react-addons-create-fragment' +```javascript +import createFragment from 'react-addons-create-fragment'; function Swapper(props) { let children; diff --git a/docs/docs/addons-perf.md b/docs/docs/addons-perf.md index aa5dfd2acc584..762c75a3e4e75 100644 --- a/docs/docs/addons-perf.md +++ b/docs/docs/addons-perf.md @@ -4,16 +4,13 @@ title: Performance Tools permalink: docs/perf.html layout: docs category: Add-Ons -prev: create-fragment.html -next: test-utils.html --- **Importing** ```javascript -import Perf from 'react-addons-perf' // ES6 -var Perf = require('react-addons-perf') // ES5 with npm -var Perf = React.addons.Perf; // ES5 with react-with-addons.js +import Perf from 'react-addons-perf'; // ES6 +var Perf = require('react-addons-perf'); // ES5 with npm ``` diff --git a/docs/docs/addons-pure-render-mixin.md b/docs/docs/addons-pure-render-mixin.md index 4d741e91b1293..02b213bdcc318 100644 --- a/docs/docs/addons-pure-render-mixin.md +++ b/docs/docs/addons-pure-render-mixin.md @@ -12,9 +12,8 @@ category: Add-Ons **Importing** ```javascript -import PureRenderMixin from 'react-addons-pure-render-mixin' // ES6 -var PureRenderMixin = require('react-addons-pure-render-mixin') // ES5 with npm -var PureRenderMixin = React.addons.PureRenderMixin; // ES5 with react-with-addons.js +import PureRenderMixin from 'react-addons-pure-render-mixin'; // ES6 +var PureRenderMixin = require('react-addons-pure-render-mixin'); // ES5 with npm ``` ## Overview @@ -24,7 +23,9 @@ If your React component's render function renders the same result given the same Example: ```js -React.createClass({ +const createReactClass = require('create-react-class'); + +createReactClass({ mixins: [PureRenderMixin], render: function() { diff --git a/docs/docs/addons-shallow-compare.md b/docs/docs/addons-shallow-compare.md index f123931d2cfa5..55e7f45d309cb 100644 --- a/docs/docs/addons-shallow-compare.md +++ b/docs/docs/addons-shallow-compare.md @@ -12,9 +12,8 @@ category: Reference **Importing** ```javascript -import shallowCompare from 'react-addons-shallow-compare' // ES6 -var shallowCompare = require('react-addons-shallow-compare') // ES5 with npm -var shallowCompare = React.addons.shallowCompare; // ES5 with react-with-addons.js +import shallowCompare from 'react-addons-shallow-compare'; // ES6 +var shallowCompare = require('react-addons-shallow-compare'); // ES5 with npm ``` ## Overview diff --git a/docs/docs/addons-shallow-renderer.md b/docs/docs/addons-shallow-renderer.md new file mode 100644 index 0000000000000..b0f3bd6b05325 --- /dev/null +++ b/docs/docs/addons-shallow-renderer.md @@ -0,0 +1,60 @@ +--- +id: shallow-renderer +title: Shallow Renderer +permalink: docs/shallow-renderer.html +layout: docs +category: Reference +--- + +**Importing** + +```javascript +import ReactShallowRenderer from 'react-test-renderer/shallow'; // ES6 +var ReactShallowRenderer = require('react-test-renderer/shallow'); // ES5 with npm +``` +### Shallow Rendering + +Shallow rendering lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM. + + - [`shallowRenderer.render()`](#shallowrenderer.render) + - [`shallowRenderer.getRenderOutput()`](#shallowrenderer.getrenderoutput) + +You can think of the shallowRenderer as a "place" to render the component you're testing, and from which you can extract the component's output. + +[`shallowRenderer.render()`](#shallowrenderer.render) is similar to [`ReactDOM.render()`](/react/docs/react-dom.html#render) but it doesn't require DOM and only renders a single level deep. This means you can test components isolated from how their children are implemented. + +After `shallowRenderer.render()` has been called, you can use [`shallowRenderer.getRenderOutput()`](#shallowrenderer.getrenderoutput) to get the shallowly rendered output. + +You can then begin to assert facts about the output. For example, if you have the following component: + +```javascript +function MyComponent() { + return ( +
+ Title + +
+ ); +} +``` + +Then you can assert: + +```javascript +const ReactShallowRenderer = require('react-test-renderer/shallow'); +const shallowRenderer = new ReactShallowRenderer(); +shallowRenderer.render(); +const result = shallowRenderer.getRenderOutput(); + +expect(result.type).toBe('div'); +expect(result.props.children).toEqual([ + Title, + +]); +``` + +Shallow testing currently has some limitations, namely not supporting refs. + +We also recommend checking out Enzyme's [Shallow Rendering API](http://airbnb.io/enzyme/docs/api/shallow.html). It provides a nicer higher-level API over the same functionality. + +* * * diff --git a/docs/docs/addons-test-utils.md b/docs/docs/addons-test-utils.md index 7f4d251e1c3c8..cda0cb2ac74c1 100644 --- a/docs/docs/addons-test-utils.md +++ b/docs/docs/addons-test-utils.md @@ -4,15 +4,13 @@ title: Test Utilities permalink: docs/test-utils.html layout: docs category: Reference -prev: perf.html --- **Importing** ```javascript -import ReactTestUtils from 'react-addons-test-utils' // ES6 -var ReactTestUtils = require('react-addons-test-utils') // ES5 with npm -var ReactTestUtils = React.addons.TestUtils; // ES5 with react-with-addons.js +import ReactTestUtils from 'react-dom/test-utils'; // ES6 +var ReactTestUtils = require('react-dom/test-utils'); // ES5 with npm ``` ## Overview @@ -39,53 +37,6 @@ var ReactTestUtils = React.addons.TestUtils; // ES5 with react-with-addons.js - [`scryRenderedComponentsWithType()`](#scryrenderedcomponentswithtype) - [`findRenderedComponentWithType()`](#findrenderedcomponentwithtype) -### Shallow Rendering - -Shallow rendering lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM. - - - [`createRenderer()`](#createrenderer) - - [`shallowRenderer.render()`](#shallowrenderer.render) - - [`shallowRenderer.getRenderOutput()`](#shallowrenderer.getrenderoutput) - -Call [`createRenderer()`](#createrenderer) in your tests to create a shallow renderer. You can think of this as a "place" to render the component you're testing, and from which you can extract the component's output. - -[`shallowRenderer.render()`](#shallowrenderer.render) is similar to [`ReactDOM.render()`](/react/docs/react-dom.html#render) but it doesn't require DOM and only renders a single level deep. This means you can test components isolated from how their children are implemented. - -After `shallowRenderer.render()` has been called, you can use [`shallowRenderer.getRenderOutput()`](#shallowrenderer.getrenderoutput) to get the shallowly rendered output. - -You can then begin to assert facts about the output. For example, if you have the following component: - -```javascript -function MyComponent() { - return ( -
- Title - -
- ); -} -``` - -Then you can assert: - -```javascript -const renderer = ReactTestUtils.createRenderer(); -renderer.render(); -const result = renderer.getRenderOutput(); - -expect(result.type).toBe('div'); -expect(result.props.children).toEqual([ - Title, - -]); -``` - -Shallow testing currently has some limitations, namely not supporting refs. - -We also recommend checking out Enzyme's [Shallow Rendering API](http://airbnb.io/enzyme/docs/api/shallow.html). It provides a nicer higher-level API over the same functionality. - -* * * - ## Reference ### `Simulate` diff --git a/docs/docs/addons-two-way-binding-helpers.md b/docs/docs/addons-two-way-binding-helpers.md index c919990ce6f51..1d08193c0bcee 100644 --- a/docs/docs/addons-two-way-binding-helpers.md +++ b/docs/docs/addons-two-way-binding-helpers.md @@ -4,8 +4,6 @@ title: Two-way Binding Helpers permalink: docs/two-way-binding-helpers.html layout: docs category: Add-Ons -prev: pure-render-mixin.html -next: update.html --- > Note: @@ -14,16 +12,15 @@ next: update.html **Importing** ```javascript -import LinkedStateMixin from 'react-addons-linked-state-mixin' // ES6 -var LinkedStateMixin = require('react-addons-linked-state-mixin') // ES5 with npm -var LinkedStateMixin = React.addons.LinkedStateMixin; // ES5 with react-with-addons.js +import LinkedStateMixin from 'react-addons-linked-state-mixin'; // ES6 +var LinkedStateMixin = require('react-addons-linked-state-mixin'); // ES5 with npm ``` ## Overview `LinkedStateMixin` is an easy way to express two-way binding with React. -In React, data flows one way: from owner to child. This is because data only flows one direction in [the Von Neumann model of computing](https://en.wikipedia.org/wiki/Von_Neumann_architecture). You can think of it as "one-way data binding." +In React, data flows one way: from owner to child. We think that this makes your app's code easier to understand. You can think of it as "one-way data binding." However, there are lots of applications that require you to read some data and flow it back into your program. For example, when developing forms, you'll often want to update some React `state` when you receive user input. Or perhaps you want to perform layout in JavaScript and react to changes in some DOM element size. @@ -40,7 +37,9 @@ Two-way binding -- implicitly enforcing that some value in the DOM is always con Here's a simple form example without using `LinkedStateMixin`: ```javascript -var NoLink = React.createClass({ +var createReactClass = require('create-react-class'); + +var NoLink = createReactClass({ getInitialState: function() { return {message: 'Hello!'}; }, @@ -57,7 +56,9 @@ var NoLink = React.createClass({ This works really well and it's very clear how data is flowing, however, with a lot of form fields it could get a bit verbose. Let's use `LinkedStateMixin` to save us some typing: ```javascript{4,9} -var WithLink = React.createClass({ +var createReactClass = require('create-react-class'); + +var WithLink = createReactClass({ mixins: [LinkedStateMixin], getInitialState: function() { return {message: 'Hello!'}; @@ -83,8 +84,10 @@ There are two sides to `LinkedStateMixin`: the place where you create the `value ### valueLink Without LinkedStateMixin -```javascript{5-7,9-12} -var WithoutMixin = React.createClass({ +```javascript{7-9,11-14} +var createReactClass = require('create-react-class'); + +var WithoutMixin = createReactClass({ getInitialState: function() { return {message: 'Hello!'}; }, @@ -107,8 +110,9 @@ As you can see, `valueLink` objects are very simple objects that just have a `va ```javascript var LinkedStateMixin = require('react-addons-linked-state-mixin'); +var createReactClass = require('create-react-class'); -var WithoutLink = React.createClass({ +var WithoutLink = createReactClass({ mixins: [LinkedStateMixin], getInitialState: function() { return {message: 'Hello!'}; diff --git a/docs/docs/addons-update.md b/docs/docs/addons-update.md index ecebc205401d4..b85ea808663bb 100644 --- a/docs/docs/addons-update.md +++ b/docs/docs/addons-update.md @@ -14,7 +14,6 @@ category: Add-Ons ```javascript import update from 'react-addons-update'; // ES6 var update = require('react-addons-update'); // ES5 with npm -var update = React.addons.update; // ES5 with react-with-addons.js ``` ## Overview diff --git a/docs/docs/addons.md b/docs/docs/addons.md index a927a4266ac47..d0f6a770b8ec4 100644 --- a/docs/docs/addons.md +++ b/docs/docs/addons.md @@ -4,9 +4,11 @@ title: Add-Ons permalink: docs/addons.html --- +>Note: +> `React.addons` is deprecated as of React v15.5. The add-ons have now all either been deprecated or moved to separate modules. + The React add-ons are a collection of useful utility modules for building React apps. **These should be considered experimental** and tend to change more often than the core. -- [`TransitionGroup` and `CSSTransitionGroup`](animation.html), for dealing with animations and transitions that are usually not simple to implement, such as before a component's removal. - [`createFragment`](create-fragment.html), to create a set of externally-keyed children. The add-ons below are in the development (unminified) version of React only: @@ -24,15 +26,16 @@ The add-ons below are considered legacy and their use is discouraged. ### Deprecated Add-ons -[`LinkedStateMixin`](two-way-binding-helpers.html) has been deprecated. +- [`LinkedStateMixin`](two-way-binding-helpers.html) has been deprecated. +- [`TransitionGroup` and `CSSTransitionGroup`](animation.html) have been deprecated. ## Using React with Add-ons -If using npm, you can install the add-ons individually from npm (e.g. `npm install react-addons-test-utils`) and import them: +You can install the add-ons individually from npm (e.g. `npm install react-addons-create-fragment`) and import them: ```javascript -import Perf from 'react-addons-perf'; // ES6 -var Perf = require('react-addons-perf'); // ES5 with npm +import createFragment from 'react-addons-create-fragment'; // ES6 +var createFragment = require('react-addons-create-fragment'); // ES5 with npm ``` When using a CDN, you can use `react-with-addons.js` instead of `react.js`: diff --git a/docs/docs/context.md b/docs/docs/context.md index c5703d3545254..718e941a06418 100644 --- a/docs/docs/context.md +++ b/docs/docs/context.md @@ -4,11 +4,15 @@ title: Context permalink: docs/context.html --- +>Note: +> As of React v15.5 the `React.PropTypes` helper is deprecated, and we recommend using the [`prop-types` library](https://www.npmjs.com/package/prop-types) to define `contextTypes`. + With React, it's easy to track the flow of data through your React components. When you look at a component, you can see which props are being passed, which makes your apps easy to reason about. In some cases, you want to pass data through the component tree without having to pass the props down manually at every level. You can do this directly in React with the powerful "context" API. + ## Why Not To Use Context The vast majority of applications do not need to use context. @@ -59,7 +63,9 @@ class MessageList extends React.Component { In this example, we manually thread through a `color` prop in order to style the `Button` and `Message` components appropriately. Using context, we can pass this through the tree automatically: -```javascript{4,11-13,19,26-28,38-40} +```javascript{6,13-15,21,28-30,40-42} +const PropTypes = require('prop-types'); + class Button extends React.Component { render() { return ( @@ -71,7 +77,7 @@ class Button extends React.Component { } Button.contextTypes = { - color: React.PropTypes.string + color: PropTypes.string }; class Message extends React.Component { @@ -98,7 +104,7 @@ class MessageList extends React.Component { } MessageList.childContextTypes = { - color: React.PropTypes.string + color: PropTypes.string }; ``` @@ -111,7 +117,7 @@ If `contextTypes` is not defined, then `context` will be an empty object. Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router): ```javascript -import { Router, Route, Link } from 'react-router-dom'; +import { BrowserRouter as Router, Route, Link } from 'react-router-dom'; const BasicExample = () => ( @@ -151,12 +157,14 @@ If `contextTypes` is defined within a component, the following [lifecycle method Stateless functional components are also able to reference `context` if `contextTypes` is defined as a property of the function. The following code shows a `Button` component written as a stateless functional component. ```javascript +const PropTypes = require('prop-types'); + const Button = ({children}, context) => ; -Button.contextTypes = {color: React.PropTypes.string}; +Button.contextTypes = {color: PropTypes.string}; ``` ## Updating Context @@ -168,6 +176,8 @@ React has an API to update context, but it is fundamentally broken and you shoul The `getChildContext` function will be called when the state or props changes. In order to update data in the context, trigger a local state update with `this.setState`. This will trigger a new context and changes will be received by the children. ```javascript +const PropTypes = require('prop-types'); + class MediaQuery extends React.Component { constructor(props) { super(props); @@ -196,7 +206,7 @@ class MediaQuery extends React.Component { } MediaQuery.childContextTypes = { - type: React.PropTypes.string + type: PropTypes.string }; ``` diff --git a/docs/docs/installation.md b/docs/docs/installation.md index d4ee06ae54422..bbbaf4cadc28b 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/jsx-in-depth.md b/docs/docs/jsx-in-depth.md index 41c3813dd8459..ded9c60102f30 100644 --- a/docs/docs/jsx-in-depth.md +++ b/docs/docs/jsx-in-depth.md @@ -152,7 +152,7 @@ function Story(props) { To fix this, we will assign the type to a capitalized variable first: -```js{9-11} +```js{10-12} import React from 'react'; import { PhotoStory, VideoStory } from './stories'; @@ -172,7 +172,7 @@ function Story(props) { There are several different ways to specify props in JSX. -### JavaScript Expressions +### JavaScript Expressions as Props You can pass any JavaScript expression as a prop, by surrounding it with `{}`. For example, in this JSX: @@ -196,6 +196,8 @@ function NumberDescriber(props) { } ``` +You can learn more about [conditional rendering](/react/docs/conditional-rendering.html) and [loops](/react/docs/lists-and-keys.html) in the corresponding sections. + ### String Literals You can pass a string literal as a prop. These two JSX expressions are equivalent: @@ -308,7 +310,7 @@ You can mix together different types of children, so you can use string literals A React component can't return multiple React elements, but a single JSX expression can have multiple children, so if you want a component to render multiple things you can wrap it in a `div` like this. -### JavaScript Expressions +### JavaScript Expressions as Children You can pass any JavaScript expression as children, by enclosing it within `{}`. For example, these expressions are equivalent: diff --git a/docs/docs/lifting-state-up.md b/docs/docs/lifting-state-up.md index 60931231cbc23..17b4406720518 100644 --- a/docs/docs/lifting-state-up.md +++ b/docs/docs/lifting-state-up.md @@ -302,7 +302,7 @@ Let's recap what happens when you edit an input: * React calls the function specified as `onChange` on the DOM ``. In our case, this is the `handleChange` method in `TemperatureInput` component. * The `handleChange` method in the `TemperatureInput` component calls `this.props.onTemperatureChange()` with the new desired value. Its props, including `onTemperatureChange`, were provided by its parent component, the `Calculator`. -* When it previously rendered, the `Calculator` has specified that `onTemperatureChange` of the Celsius `TemperatureInput` is the `Calculator`'s `handleCelsiusChange` method, and `onTemperatureChange` of the Fahrenheit `TemperatureInput` is the `Calculator`'s `handleFahrehnheitChange` method. So either of these two `Calculator` methods gets called depending on which input we edited. +* When it previously rendered, the `Calculator` has specified that `onTemperatureChange` of the Celsius `TemperatureInput` is the `Calculator`'s `handleCelsiusChange` method, and `onTemperatureChange` of the Fahrenheit `TemperatureInput` is the `Calculator`'s `handleFahrenheitChange` method. So either of these two `Calculator` methods gets called depending on which input we edited. * Inside these methods, the `Calculator` component asks React to re-render itself by calling `this.setState()` with the new input value and the current scale of the input we just edited. * React calls the `Calculator` component's `render` method to learn what the UI should look like. The values of both inputs are recomputed based on the current temperature and the active scale. The temperature conversion is performed here. * React calls the `render` methods of the individual `TemperatureInput` components with their new props specified by the `Calculator`. It learns what their UI should look like. diff --git a/docs/docs/react-without-es6.md b/docs/docs/react-without-es6.md index 84fa1fefe7f06..e49a5e0757088 100644 --- a/docs/docs/react-without-es6.md +++ b/docs/docs/react-without-es6.md @@ -14,45 +14,38 @@ class Greeting extends React.Component { } ``` -If you don't use ES6 yet, you may use the `React.createClass` helper instead: +If you don't use ES6 yet, you may use the `create-react-class` module instead: ```javascript -var Greeting = React.createClass({ +var createReactClass = require('create-react-class'); +var Greeting = createReactClass({ render: function() { return

Hello, {this.props.name}

; } }); ``` -The API of ES6 classes is similar to `React.createClass` with a few exceptions. +The API of ES6 classes is similar to `createReactClass()` with a few exceptions. -## Declaring Prop Types and Default Props +## Declaring Default Props -With functions and ES6 classes, `propTypes` and `defaultProps` are defined as properties on the components themselves: +With functions and ES6 classes `defaultProps` is defined as a property on the component itself: ```javascript class Greeting extends React.Component { // ... } -Greeting.propTypes = { - name: React.PropTypes.string -}; - Greeting.defaultProps = { name: 'Mary' }; ``` -With `React.createClass()`, you need to define `propTypes` as a property on the passed object, and `getDefaultProps()` as a function on it: +With `createReactClass()`, you need to define `getDefaultProps()` as a function on the passed object: ```javascript -var Greeting = React.createClass({ - propTypes: { - name: React.PropTypes.string - }, - +var Greeting = createReactClass({ getDefaultProps: function() { return { name: 'Mary' @@ -78,10 +71,10 @@ class Counter extends React.Component { } ``` -With `React.createClass()`, you have to provide a separate `getInitialState` method that returns the initial state: +With `createReactClass()`, you have to provide a separate `getInitialState` method that returns the initial state: ```javascript -var Counter = React.createClass({ +var Counter = createReactClass({ getInitialState: function() { return {count: this.props.initialCount}; }, @@ -117,14 +110,14 @@ class SayHello extends React.Component { } ``` -With `React.createClass()`, this is not necessary because it binds all methods: +With `createReactClass()`, this is not necessary because it binds all methods: ```javascript -var SayHello = React.createClass({ +var SayHello = createReactClass({ getInitialState: function() { return {message: 'Hello!'}; }, - + handleClick: function() { alert(this.state.message); }, @@ -172,7 +165,7 @@ If you'd rather play it safe, you have a few options: * Bind methods in the constructor. * Use arrow functions, e.g. `onClick={(e) => this.handleClick(e)}`. -* Keep using `React.createClass()`. +* Keep using `createReactClass`. ## Mixins @@ -184,7 +177,7 @@ If you'd rather play it safe, you have a few options: > >This section exists only for the reference. -Sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](https://en.wikipedia.org/wiki/Cross-cutting_concern). [`React.createClass`](/react/docs/top-level-api.html#react.createclass) lets you use a legacy `mixins` system for that. +Sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](https://en.wikipedia.org/wiki/Cross-cutting_concern). [`createReactClass`](/react/docs/top-level-api.html#react.createclass) lets you use a legacy `mixins` system for that. One common use case is a component wanting to update itself on a time interval. It's easy to use `setInterval()`, but it's important to cancel your interval when you don't need it anymore to save memory. React provides [lifecycle methods](/react/docs/working-with-the-browser.html#component-lifecycle) that let you know when a component is about to be created or destroyed. Let's create a simple mixin that uses these methods to provide an easy `setInterval()` function that will automatically get cleaned up when your component is destroyed. @@ -201,7 +194,9 @@ var SetIntervalMixin = { } }; -var TickTock = React.createClass({ +var createReactClass = require('create-react-class'); + +var TickTock = createReactClass({ mixins: [SetIntervalMixin], // Use the mixin getInitialState: function() { return {seconds: 0}; diff --git a/docs/docs/reference-pure-render-mixin.md b/docs/docs/reference-pure-render-mixin.md index 4b2e5a439dbfd..cee8bcaa948bd 100644 --- a/docs/docs/reference-pure-render-mixin.md +++ b/docs/docs/reference-pure-render-mixin.md @@ -16,7 +16,8 @@ Example: ```js var PureRenderMixin = require('react-addons-pure-render-mixin'); -React.createClass({ +var createReactClass = require('create-react-class'); +createReactClass({ mixins: [PureRenderMixin], render: function() { diff --git a/docs/docs/reference-react-component.md b/docs/docs/reference-react-component.md index b274da6edf332..2c1b0770cb871 100644 --- a/docs/docs/reference-react-component.md +++ b/docs/docs/reference-react-component.md @@ -31,7 +31,7 @@ class Greeting extends React.Component { } ``` -If you don't use ES6 yet, you may use the [`React.createClass`](/react/docs/react-api.html#createclass) helper instead. Take a look at [Using React without ES6](/react/docs/react-without-es6.html) to learn more. +If you don't use ES6 yet, you may use the [`create-react-class`](/react/docs/react-api.html#createclass) module instead. Take a look at [Using React without ES6](/react/docs/react-without-es6.html) to learn more. ### The Component Lifecycle @@ -73,7 +73,6 @@ Each component also provides some other APIs: - [`defaultProps`](#defaultprops) - [`displayName`](#displayname) - - [`propTypes`](#proptypes) ### Instance Properties @@ -114,7 +113,7 @@ The constructor for a React component is called before it is mounted. When imple The constructor is the right place to initialize state. If you don't initialize state and you don't bind methods, you don't need to implement a constructor for your React component. -It's okay to initialize state based on props if you know what you're doing. Here's an example of a valid `React.Component` subclass constructor: +It's okay to initialize state based on props. This effectively "forks" the props and sets the state with the initial props. Here's an example of a valid `React.Component` subclass constructor: ```js constructor(props) { @@ -122,10 +121,10 @@ constructor(props) { this.state = { color: props.initialColor }; -} +} ``` -Beware of this pattern, as it effectively "forks" the props and can lead to bugs. Instead of syncing props to state, you often want to [lift the state up](/react/docs/lifting-state-up.html). +Beware of this pattern, as state won't be up-to-date with any props update. Instead of syncing props to state, you often want to [lift the state up](/react/docs/lifting-state-up.html). If you "fork" props by using them for state, you might also want to implement [`componentWillReceiveProps(nextProps)`](#componentwillreceiveprops) to keep the state up-to-date with them. But lifting state up is often easier and less bug-prone. @@ -137,7 +136,7 @@ If you "fork" props by using them for state, you might also want to implement [` componentWillMount() ``` -`componentWillMount()` is invoked immediately before mounting occurs. It is called before `render()`, therefore setting state in this method will not trigger a re-rendering. Avoid introducing any side-effects or subscriptions in this method. +`componentWillMount()` is invoked immediately before mounting occurs. It is called before `render()`, therefore setting state synchronously in this method will not trigger a re-rendering. Avoid introducing any side-effects or subscriptions in this method. This is the only lifecycle hook called on server rendering. Generally, we recommend using the `constructor()` instead. @@ -230,34 +229,67 @@ componentWillUnmount() ### `setState()` ```javascript -setState(nextState, callback) +setState(updater, [callback]) ``` -Performs a shallow merge of nextState into current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. +`setState()` enqueues changes to the component state and tells React that this component and its children need to be re-rendered with the updated state. This is the primary method you use to update the user interface in response to event handlers and server responses. + +Think of `setState()` as a *request* rather than an immediate command to update the component. For better perceived performance, React may delay it, and then update several components in a single pass. React does not guarantee that the state changes are applied immediately. -The first argument can be an object (containing zero or more keys to update) or a function (of state and props) that returns an object containing keys to update. +`setState()` does not always immediately update the component. It may batch or defer the update until later. This makes reading `this.state` right after calling `setState()` a potential pitfall. Instead, use `componentDidUpdate` or a `setState` callback (`setState(updater, callback)`), either of which are guaranteed to fire after the update has been applied. If you need to set the state based on the previous state, read about the `updater` argument below. -Here is the simple object usage: +`setState()` will always lead to a re-render unless `shouldComponentUpdate()` returns `false`. If mutable objects are being used and conditional rendering logic cannot be implemented in `shouldComponentUpdate()`, calling `setState()` only when the new state differs from the previous state will avoid unnecessary re-renders. + +The first argument is an `updater` function with the signature: ```javascript -this.setState({mykey: 'my new value'}); +(prevState, props) => nextState ``` -It's also possible to pass a function with the signature `function(state, props) => newState`. This enqueues an atomic update that consults the previous value of state and props before setting any values. For instance, suppose we wanted to increment a value in state by `props.step`: +`prevState` is a reference to the previous state. It should not be directly mutated. Instead, changes should be represented by building a new state object based on the input from `prevState` and `props`. For instance, suppose we wanted to increment a value in state by `props.step`: ```javascript this.setState((prevState, props) => { - return {myInteger: prevState.myInteger + props.step}; + return {counter: prevState.counter + props.step}; }); ``` -The second parameter is an optional callback function that will be executed once `setState` is completed and the component is re-rendered. Generally we recommend using `componentDidUpdate()` for such logic instead. +Both `prevState` and `props` received by the updater function are guaranteed to be up-to-date. -`setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value. +The second parameter to `setState()` is an optional callback function that will be executed once `setState` is completed and the component is re-rendered. Generally we recommend using `componentDidUpdate()` for such logic instead. -There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains. +You may optionally pass an object as the first argument to `setState()` instead of a function: -`setState()` will always lead to a re-render unless `shouldComponentUpdate()` returns `false`. If mutable objects are being used and conditional rendering logic cannot be implemented in `shouldComponentUpdate()`, calling `setState()` only when the new state differs from the previous state will avoid unnecessary re-renders. +```javascript +setState(stateChange, [callback]) +``` + +This performs a shallow merge of `stateChange` into the new state, e.g., to adjust a shopping cart item quantity: + +```javascript +this.setState({quantity: 2}) +``` + +This form of `setState()` is also asynchronous, and multiple calls during the same cycle may be batched together. For example, if you attempt to increment an item quantity more than once in the same cycle, that will result in the equivalent of: + +```javaScript +Object.assign( + previousState, + {quantity: state.quantity + 1}, + {quantity: state.quantity + 1}, + ... +) +``` + +Subsequent calls will override values from previous calls in the same cycle, so the quantity will only be incremented once. If the next state depends on the previous state, we recommend using the updater function form, instead: + +```js +this.setState((prevState) => { + return {counter: prevState.quantity + 1}; +}); +``` + +For more detail, see the [State and Lifecycle guide](/react/docs/state-and-lifecycle.html). * * * @@ -315,26 +347,6 @@ The `displayName` string is used in debugging messages. JSX sets this value auto * * * -### `propTypes` - -`propTypes` can be defined as a property on the component class itself, to define what types the props should be. It should be a map from prop names to types as defined in [`React.PropTypes`](/react/docs/react-api.html#react.proptypes). In development mode, when an invalid value is provided for a prop, a warning will be shown in the JavaScript console. In production mode, `propTypes` checks are skipped for efficiency. - -For example, this code ensures that the `color` prop is a string: - -```js -class CustomButton extends React.Component { - // ... -} - -CustomButton.propTypes = { - color: React.PropTypes.string -}; -``` - -We recommend using [Flow](https://flowtype.org/) when possible, to get compile-time typechecking instead of runtime typechecking. [Flow has built-in support for React](https://flowtype.org/docs/react.html) so it's easy to run static analysis on a React app. - -* * * - ## Instance Properties ### `props` diff --git a/docs/docs/reference-react.md b/docs/docs/reference-react.md index a00770a2fb5f9..abcdfd91b05a1 100644 --- a/docs/docs/reference-react.md +++ b/docs/docs/reference-react.md @@ -25,9 +25,7 @@ React components let you split the UI into independent, reusable pieces, and thi - [`React.Component`](#react.component) - [`React.PureComponent`](#react.purecomponent) -If you don't use ES6 classes, you may use this helper instead. - - - [`createClass()`](#createclass) +If you don't use ES6 classes, you may use the `create-react-class` module instead. See [Using React without ES6](/react/docs/react-without-es6.html) for more information. ### Creating React Elements @@ -46,38 +44,6 @@ See [Using React without JSX](/react/docs/react-without-jsx.html) for more infor - [`isValidElement()`](#isvalidelement) - [`React.Children`](#react.children) -### Typechecking with PropTypes - -You can use `React.PropTypes` to run typechecking on the props for a component. - - - [`React.PropTypes`](#react.proptypes) - - [`React.PropTypes.array`](#react.proptypes.array) - - [`React.PropTypes.bool`](#react.proptypes.bool) - - [`React.PropTypes.func`](#react.proptypes.func) - - [`React.PropTypes.number`](#react.proptypes.number) - - [`React.PropTypes.object`](#react.proptypes.object) - - [`React.PropTypes.string`](#react.proptypes.string) - - [`React.PropTypes.symbol`](#react.proptypes.symbol) - - [`React.PropTypes.node`](#react.proptypes.node) - - [`React.PropTypes.element`](#react.proptypes.element) - - [`React.PropTypes.instanceOf()`](#react.proptypes.instanceof) - - [`React.PropTypes.oneOf()`](#react.proptypes.oneof) - - [`React.PropTypes.oneOfType()`](#react.proptypes.oneoftype) - - [`React.PropTypes.arrayOf()`](#react.proptypes.arrayof) - - [`React.PropTypes.objectOf()`](#react.proptypes.objectof) - - [`React.PropTypes.shape()`](#react.proptypes.shape) - - [`React.PropTypes.any`](#react.proptypes.any) - -Validators treat props as optional by default. You can use `isRequired` to make sure a warning is shown if the prop is not provided. - - - [`isRequired`](#isrequired) - -### Add-Ons - -If you're using [`react-with-addons.js`](/react/docs/addons.html), the React Add-Ons will be available via `React.addons`. - - - [`React.addons`](#react.addons) - * * * ## Reference @@ -112,26 +78,6 @@ If your React component's `render()` function renders the same result given the * * * -### `createClass()` - -```javascript -React.createClass(specification) -``` - -If you don't use ES6 yet, you may use the `React.createClass()` helper instead to create a component class. - -```javascript -var Greeting = React.createClass({ - render: function() { - return

Hello, {this.props.name}

; - } -}); -``` - -See [Using React without ES6](/react/docs/react-without-es6.html) for more information. - -* * * - ### `createElement()` ```javascript @@ -245,206 +191,3 @@ Returns the `children` opaque data structure as a flat array with keys assigned > Note: > > `React.Children.toArray()` changes keys to preserve the semantics of nested arrays when flattening lists of children. That is, `toArray` prefixes each key in the returned array so that each element's key is scoped to the input array containing it. - -* * * - -### `React.PropTypes` - -`React.PropTypes` exports a range of validators that can be used with a component's `propTypes` object to validate props being passed to your components. - -For more information about `PropTypes`, see [Typechecking with PropTypes](/react/docs/typechecking-with-proptypes.html). - -#### `React.PropTypes.array` - -```javascript -React.PropTypes.array -``` - -Validates that a prop is a JavaScript array primitive. - -#### `React.PropTypes.bool` - -```javascript -React.PropTypes.bool -``` - -Validates that a prop is a JavaScript bool primitive. - -#### `React.PropTypes.func` - -```javascript -React.PropTypes.func -``` - -Validates that a prop is a JavaScript function. - -#### `React.PropTypes.number` - -```javascript -React.PropTypes.number -``` - -Validates that a prop is a JavaScript number primitive. - -#### `React.PropTypes.object` - -```javascript -React.PropTypes.object -``` - -Validates that a prop is a JavaScript object. - -#### `React.PropTypes.string` - -```javascript -React.PropTypes.string -``` - -Validates that a prop is a JavaScript string primitive. - -#### `React.PropTypes.symbol` - -```javascript -React.PropTypes.symbol -``` - -Validates that a prop is a JavaScript symbol. - -#### `React.PropTypes.node` - -```javascript -React.PropTypes.node -``` - -Validates that a prop is anything that can be rendered: numbers, strings, elements or an array (or fragment) containing these types. - -#### `React.PropTypes.element` - -```javascript -React.PropTypes.element -``` - -Validates that a prop is a React element. - -#### `React.PropTypes.instanceOf()` - -```javascript -React.PropTypes.instanceOf(class) -``` - -Validates that a prop is an instance of a class. This uses JavaScript's `instanceof` operator. - -#### `React.PropTypes.oneOf()` - -```javascript -React.PropTypes.oneOf(arrayOfValues) -``` - -Validates that a prop is limited to specific values by treating it as an enum. - -```javascript -MyComponent.propTypes = { - optionalEnum: React.PropTypes.oneOf(['News', 'Photos']), -} -``` - -#### `React.PropTypes.oneOfType()` - -```javascript -React.PropTypes.oneOfType(arrayOfPropTypes) -``` - -Validates that a prop is an object that could be one of many types. - -```javascript -MyComponent.propTypes = { - optionalUnion: React.PropTypes.oneOfType([ - React.PropTypes.string, - React.PropTypes.number, - React.PropTypes.instanceOf(Message) - ]), -} -``` - -#### `React.PropTypes.arrayOf()` - -```javascript -React.PropTypes.arrayOf(propType) -``` - -Validates that a prop is an array of a certain type. - -```javascript -MyComponent.propTypes = { - optionalArrayOf: React.PropTypes.arrayOf(React.PropTypes.number), -} -``` - -#### `React.PropTypes.objectOf()` - -```javascript -React.PropTypes.objectOf(propType) -``` - -Validates that a prop is an object with property values of a certain type. - -```javascript -MyComponent.propTypes = { - optionalObjectOf: React.PropTypes.objectOf(React.PropTypes.number), -} -``` - -#### `React.PropTypes.shape()` - -```javascript -React.PropTypes.shape(object) -``` - -Validates that a prop is an object taking on a particular shape. - -```javascript -MyComponent.propTypes = { - optionalObjectWithShape: React.PropTypes.shape({ - color: React.PropTypes.string, - fontSize: React.PropTypes.number - }), -} -``` - -#### `React.PropTypes.any` - -```javascript -React.PropTypes.any -``` - -Validates that a prop has a value of any data type. Usually followed by `isRequired`. - -```javascript -MyComponent.propTypes = { - requiredAny: React.PropTypes.any.isRequired, -} -``` - -### `isRequired` - -```javascript -propType.isRequired -``` - -You can chain any of the above validators with `isRequired` to make sure a warning is shown if the prop is not provided. - -```javascript -MyComponent.propTypes = { - requiredFunc: React.PropTypes.func.isRequired, -} -``` - -* * * - -### `React.addons` - -```javascript -React.addons -``` - -`React.addons` exports a range of add-ons when using [`react-with-addons.js`](/react/docs/addons.html). diff --git a/docs/docs/typechecking-with-proptypes.md b/docs/docs/typechecking-with-proptypes.md index e3c4abd200cb1..85c128d3a909f 100644 --- a/docs/docs/typechecking-with-proptypes.md +++ b/docs/docs/typechecking-with-proptypes.md @@ -2,11 +2,18 @@ id: typechecking-with-proptypes title: Typechecking With PropTypes permalink: docs/typechecking-with-proptypes.html +redirect_from: + - "docs/react-api.html#typechecking-with-proptypes" --- +> Note: +> `React.PropTypes` is deprecated as of React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types). + As your app grows, you can catch a lot of bugs with typechecking. For some applications, you can use JavaScript extensions like [Flow](https://flowtype.org/) or [TypeScript](https://www.typescriptlang.org/) to typecheck your whole application. But even if you don't use those, React has some built-in typechecking abilities. To run typechecking on the props for a component, you can assign the special `propTypes` property: ```javascript +import PropTypes from 'prop-types'; + class Greeting extends React.Component { render() { return ( @@ -16,68 +23,70 @@ class Greeting extends React.Component { } Greeting.propTypes = { - name: React.PropTypes.string + name: PropTypes.string }; ``` -`React.PropTypes` exports a range of validators that can be used to make sure the data you receive is valid. In this example, we're using `React.PropTypes.string`. When an invalid value is provided for a prop, a warning will be shown in the JavaScript console. For performance reasons, `propTypes` is only checked in development mode. +`PropTypes` exports a range of validators that can be used to make sure the data you receive is valid. In this example, we're using `PropTypes.string`. When an invalid value is provided for a prop, a warning will be shown in the JavaScript console. For performance reasons, `propTypes` is only checked in development mode. -### React.PropTypes +### PropTypes Here is an example documenting the different validators provided: ```javascript +import PropTypes from 'prop-types'; + MyComponent.propTypes = { // You can declare that a prop is a specific JS primitive. By default, these // are all optional. - optionalArray: React.PropTypes.array, - optionalBool: React.PropTypes.bool, - optionalFunc: React.PropTypes.func, - optionalNumber: React.PropTypes.number, - optionalObject: React.PropTypes.object, - optionalString: React.PropTypes.string, - optionalSymbol: React.PropTypes.symbol, + optionalArray: PropTypes.array, + optionalBool: PropTypes.bool, + optionalFunc: PropTypes.func, + optionalNumber: PropTypes.number, + optionalObject: PropTypes.object, + optionalString: PropTypes.string, + optionalSymbol: PropTypes.symbol, // Anything that can be rendered: numbers, strings, elements or an array // (or fragment) containing these types. - optionalNode: React.PropTypes.node, + optionalNode: PropTypes.node, // A React element. - optionalElement: React.PropTypes.element, + optionalElement: PropTypes.element, // You can also declare that a prop is an instance of a class. This uses // JS's instanceof operator. - optionalMessage: React.PropTypes.instanceOf(Message), + optionalMessage: PropTypes.instanceOf(Message), // You can ensure that your prop is limited to specific values by treating // it as an enum. - optionalEnum: React.PropTypes.oneOf(['News', 'Photos']), + optionalEnum: PropTypes.oneOf(['News', 'Photos']), // An object that could be one of many types - optionalUnion: React.PropTypes.oneOfType([ - React.PropTypes.string, - React.PropTypes.number, - React.PropTypes.instanceOf(Message) + optionalUnion: PropTypes.oneOfType([ + PropTypes.string, + PropTypes.number, + PropTypes.instanceOf(Message) ]), // An array of a certain type - optionalArrayOf: React.PropTypes.arrayOf(React.PropTypes.number), + optionalArrayOf: PropTypes.arrayOf(PropTypes.number), // An object with property values of a certain type - optionalObjectOf: React.PropTypes.objectOf(React.PropTypes.number), + optionalObjectOf: PropTypes.objectOf(PropTypes.number), // An object taking on a particular shape - optionalObjectWithShape: React.PropTypes.shape({ - color: React.PropTypes.string, - fontSize: React.PropTypes.number + optionalObjectWithShape: PropTypes.shape({ + color: PropTypes.string, + fontSize: PropTypes.number }), // You can chain any of the above with `isRequired` to make sure a warning // is shown if the prop isn't provided. - requiredFunc: React.PropTypes.func.isRequired, + requiredFunc: PropTypes.func.isRequired, // A value of any data type - requiredAny: React.PropTypes.any.isRequired, + requiredAny: PropTypes.any.isRequired, // You can also specify a custom validator. It should return an Error // object if the validation fails. Don't `console.warn` or throw, as this @@ -96,7 +105,7 @@ MyComponent.propTypes = { // will be called for each key in the array or object. The first two // arguments of the validator are the array or object itself, and the // current item's key. - customArrayProp: React.PropTypes.arrayOf(function(propValue, key, componentName, location, propFullName) { + customArrayProp: PropTypes.arrayOf(function(propValue, key, componentName, location, propFullName) { if (!/matchme/.test(propValue[key])) { return new Error( 'Invalid prop `' + propFullName + '` supplied to' + @@ -109,9 +118,11 @@ MyComponent.propTypes = { ### Requiring Single Child -With `React.PropTypes.element` you can specify that only a single child can be passed to a component as children. +With `PropTypes.element` you can specify that only a single child can be passed to a component as children. ```javascript +import PropTypes from 'prop-types'; + class MyComponent extends React.Component { render() { // This must be exactly one element or it will warn. @@ -125,7 +136,7 @@ class MyComponent extends React.Component { } MyComponent.propTypes = { - children: React.PropTypes.element.isRequired + children: PropTypes.element.isRequired }; ``` diff --git a/docs/docs/uncontrolled-components.md b/docs/docs/uncontrolled-components.md index 2eaac55f6ffd8..d9fa20ac80a5a 100644 --- a/docs/docs/uncontrolled-components.md +++ b/docs/docs/uncontrolled-components.md @@ -63,4 +63,4 @@ render() { } ``` -Likewise, `` and `` support `defaultChecked`, and `` and `` support `defaultChecked`, and `