Update docs for stable Hooks

content/blog/2019-02-04-react-v16.8.0.md

@@ -0,0 +1,159 @@
+---
+title: "React v16.8: The One With Hooks"
+author: [gaearon]
+---
+
+With React 16.8, [React Hooks](/docs/hooks-intro.html) are available in a stable release!
+
+## What Are Hooks?
+
+Hooks let you use state and other React features without writing a class. You can also **build your own Hooks** to share reusable stateful logic between components.
+
+If you've never heard of Hooks before, you might find these resources interesting:
+
+* [Introducing Hooks](/docs/hooks-intro.html) explains why we're adding Hooks to React.
+* [Hooks at a Glance](/docs/hooks-overview.html) is a fast-paced overview of the built-in Hooks.
+* [Building Your Own Hooks](/docs/hooks-custom.html) demonstrates code reuse with custom Hooks.
+* [Making Sense of React Hooks](https://medium.com/@dan_abramov/making-sense-of-react-hooks-fdbde8803889) explores the new possibilities unlocked by Hooks.
+* [useHooks.com](https://usehooks.com/) showcases community-maintained Hooks recipes and demos.
+
+**You don't have to learn Hooks right now.** Hooks have no breaking changes, and we have no plans to remove classes from React. The [Hooks FAQ](/docs/hooks-faq.html) describes the gradual adoption strategy.
+
+## No Big Rewrites
+
+We don't recommend rewriting your existing applications to use Hooks overnight. Instead, try using Hooks in some of the new components, and let us know what you think. Code using Hooks will work [side by side](/docs/hooks-intro.html#gradual-adoption-strategy) with your existing code using classes.
+
+## Can I Use Hooks Today?
+
+Yes! Starting with 16.8.0, React includes a stable implementation of React Hooks for:
+
+* React DOM
+* React DOM Server
+* React Test Renderer
+* React Shallow Renderer
+
+Note that **to enable Hooks, all React packages need to be 16.8.0 or higher**. Hooks won't work if you forget to update, for example, React DOM.
+
+**React Native will fully support Hooks in its next stable release.**
+
+The final TypeScript and Flow definitions are currently in review and will be available soon.
+
+## Tooling Support
+
+React Hooks are now fully supported by React DevTools. They are also supported in the latest Flow and TypeScript definitions for React. We strongly recommend enabling a new [lint rule called `eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) to enforce best practices with Hooks. It will soon be included into Create React App by default.
+
+## What's Next
+
+We described our plan for the next months in the recently published [React Roadmap](/blog/2018/11/27/react-16-roadmap.html).
+
+Note that React Hooks don't cover *all* use cases for classes yet but they're [very close](/docs/hooks-faq.html#do-hooks-cover-all-use-cases-for-classes). Currently, only `getSnapshotBeforeUpdate()` and `componentDidCatch()` methods don't have equivalent Hooks APIs, and these lifecycles are relatively uncommon. If you want, you should be able to use Hooks in most of the new code you're writing.
+
+Even while Hooks were in alpha, we saw many [interesting examples](https://medium.com/@drcmda/hooks-in-react-spring-a-tutorial-c6c436ad7ee4) of custom Hooks for animations, forms, subscriptions, integrating with other libraries, and so on. We're excited about Hooks because they make code reuse easier, helping you write your components in a simpler way and make great user experiences. We can't wait to see what you'll create next!
+
+## Thanks
+
+We'd like to thank everybody who commented on the [Hooks RFC](https://github.com/reactjs/rfcs/pull/68) for sharing their feedback. We've read all of your comments and made some adjustments to the final API based on them.
+
+## Breaking Changes from Alpha Versions
+
+React 16.8.0 is the first **stable** release supporting Hooks.
+
+Over the past few months, we have also provided several **alpha** versions for community feedback: `16.7.0-alpha.0`, `16.7.0-alpha.1`, `16.7.0-alpha.2`, and `16.8.0-alpha.0`.
+
+**We don't recommend depending on alphas in production code.** We publish them so we can make breaking changes in response to community feedback before the API is stable.
+
+Here is a list of all breaking changes to Hooks between the first alpha and the stable release:
+
+* Remove `useMutationEffect`. ([@sophiebits](https://github.com/sophiebits) in [#14336](https://github.com/facebook/react/pull/14336))
+* Rename `useImperativeMethods` to `useImperativeHandle`. ([@threepointone](https://github.com/threepointone) in [#14565](https://github.com/facebook/react/pull/14565))
+* Bail out of rendering on identical values for `useState` and `useReducer` Hooks. ([@acdlite](https://github.com/acdlite) in [#14569](https://github.com/facebook/react/pull/14569))
+* Don’t compare the first argument passed to `useEffect`/`useMemo`/`useCallback` Hooks. ([@acdlite](https://github.com/acdlite) in [#14594](https://github.com/facebook/react/pull/14594))
+* Render components with Hooks twice in Strict Mode (DEV-only). ([@gaearon](https://github.com/gaearon) in [#14654](https://github.com/facebook/react/pull/14654))
+* Improve the `useReducer` Hook lazy initialization API. ([@acdlite](https://github.com/acdlite) in [#14723](https://github.com/facebook/react/pull/14723))
+
+Read more about our [versioning policy and commitment to stability](/docs/faq-versioning.html).
+
+## Installation
+
+### React
+
+React v16.8.0 is available on the npm registry.
+
+To install React 16 with Yarn, run:
+
+```bash
+yarn add react@^16.8.0 react-dom@^16.8.0
+```
+
+To install React 16 with npm, run:
+
+```bash
+npm install --save react@^16.8.0 react-dom@^16.8.0
+```
+
+We also provide UMD builds of React via a CDN:
+
+```html
+<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
+```
+
+Refer to the documentation for [detailed installation instructions](/docs/installation.html).
+
+### ESLint Plugin for React Hooks
+
+>Note
+>
+>If you're using Create React App, instead of manually configuring ESLint you can wait for the next version of `react-scripts` which will come out shortly and will include this rule.
+
+Assuming you already have ESLint installed, run:
+
+```sh
+# npm
+npm install eslint-plugin-react-hooks@next --save-dev
+
+# yarn
+yarn add eslint-plugin-react-hooks@next --dev
+```
+
+Then add it to your ESLint configuration:
+
+```js
+{
+  "plugins": [
+    // ...
+    "react-hooks"
+  ],
+  "rules": {
+    // ...
+    "react-hooks/rules-of-hooks": "error"
+  }
+}
+```
+
+## Changelog
+
+### React
+
+* Add [Hooks](https://reactjs.org/docs/hooks-intro.html) — a way to use state and other React features without writing a class. ([@acdlite](https://github.com/acdlite) et al. in [#13968](https://github.com/facebook/react/pull/13968))
+* Improve the `useReducer` Hook lazy initialization API. ([@acdlite](https://github.com/acdlite) in [#14723](https://github.com/facebook/react/pull/14723))
+
+### React DOM
+
+* Bail out of rendering on identical values for `useState` and `useReducer` Hooks. ([@acdlite](https://github.com/acdlite) in [#14569](https://github.com/facebook/react/pull/14569))
+* Don’t compare the first argument passed to `useEffect`/`useMemo`/`useCallback` Hooks. ([@acdlite](https://github.com/acdlite) in [#14594](https://github.com/facebook/react/pull/14594))
+* Support synchronous thenables passed to `React.lazy()`. ([@gaearon](https://github.com/gaearon) in [#14626](https://github.com/facebook/react/pull/14626))
+* Render components with Hooks twice in Strict Mode (DEV-only) to match class behavior. ([@gaearon](https://github.com/gaearon) in [#14654](https://github.com/facebook/react/pull/14654))
+* Warn about mismatching Hook order in development. ([@threepointone](https://github.com/threepointone) in [#14585](https://github.com/facebook/react/pull/14585) and [@acdlite](https://github.com/acdlite) in [#14591](https://github.com/facebook/react/pull/14591))
+
+
+### React Test Renderer
+
+* Support Hooks in the shallow renderer. ([@trueadm](https://github.com/trueadm) in [#14567](https://github.com/facebook/react/pull/14567))
+* Fix wrong state in `shouldComponentUpdate` in the presence of `getDerivedStateFromProps` for Shallow Renderer. ([@chenesan](https://github.com/chenesan) in [#14613](https://github.com/facebook/react/pull/14613))
+
+### ESLint Plugin: React Hooks
+
+* Initial [release](https://www.npmjs.com/package/eslint-plugin-react-hooks). ([@calebmer](https://github.com/calebmer) in [#13968](https://github.com/facebook/react/pull/13968))
+* Fix reporting after encountering a loop. ([@calebmer](https://github.com/calebmer) and [@Yurickh](https://github.com/Yurickh) in [#14661](https://github.com/facebook/react/pull/14661))
+* Don't consider throwing to be a rule violation. ([@sophiebits](https://github.com/sophiebits) in [#14040](https://github.com/facebook/react/pull/14040))

content/docs/hooks-custom.md

@@ -6,14 +6,14 @@ next: hooks-reference.html
 prev: hooks-rules.html
 ---
 
-*Hooks* are an upcoming feature that lets you use state and other React features without writing a class. They're currently in React v16.8.0-alpha.1.
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
 
 Building your own Hooks lets you extract component logic into reusable functions.
 
 When we were learning about [using the Effect Hook](/docs/hooks-effect.html#example-using-hooks-1), we saw this component from a chat application that displays a message indicating whether a friend is online or offline:
 
 ```js{4-15}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function FriendStatus(props) {
   const [isOnline, setIsOnline] = useState(null);
@@ -39,7 +39,7 @@ function FriendStatus(props) {
 Now let's say that our chat application also has a contact list, and we want to render names of online users with a green color. We could copy and paste similar logic above into our `FriendListItem` component but it wouldn't be ideal:
 
 ```js{4-15}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function FriendListItem(props) {
   const [isOnline, setIsOnline] = useState(null);
@@ -74,7 +74,7 @@ When we want to share logic between two JavaScript functions, we extract it to a
 **A custom Hook is a JavaScript function whose name starts with "`use`" and that may call other Hooks.** For example, `useFriendStatus` below is our first custom Hook:
 
 ```js{3}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function useFriendStatus(friendID) {
   const [isOnline, setIsOnline] = useState(null);

content/docs/hooks-effect.md

@@ -6,12 +6,12 @@ next: hooks-rules.html
 prev: hooks-intro.html
 ---
 
-*Hooks* are an upcoming feature that lets you use state and other React features without writing a class. They're currently in React v16.8.0-alpha.1.
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
 
 The *Effect Hook* lets you perform side effects in function components:
 
 ```js{1,6-10}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function Example() {
   const [count, setCount] = useState(0);
@@ -94,7 +94,7 @@ Now let's see how we can do the same with the `useEffect` Hook.
 We've already seen this example at the top of this page, but let's take a closer look at it:
 
 ```js{1,6-8}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function Example() {
   const [count, setCount] = useState(0);
@@ -199,7 +199,7 @@ Let's see how we could write this component with Hooks.
 You might be thinking that we'd need a separate effect to perform the cleanup. But code for adding and removing a subscription is so tightly related that `useEffect` is designed to keep it together. If your effect returns a function, React will run it when it is time to clean up:
 
 ```js{10-16}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function FriendStatus(props) {
   const [isOnline, setIsOnline] = useState(null);

content/docs/hooks-faq.md

@@ -5,7 +5,7 @@ permalink: docs/hooks-faq.html
 prev: hooks-reference.html
 ---
 
-*Hooks* are an upcoming feature that lets you use state and other React features without writing a class. They're currently in React v16.8.0-alpha.1.
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
 
 This page answers some of the frequently asked questions about [Hooks](/docs/hooks-overview.html).
 
@@ -19,7 +19,9 @@ This page answers some of the frequently asked questions about [Hooks](/docs/hoo
 -->
 
 * **[Adoption Strategy](#adoption-strategy)**
+  * [Which versions of React include Hooks?](#which-versions-of-react-include-hooks)
   * [Do I need to rewrite all my class components?](#do-i-need-to-rewrite-all-my-class-components)
+  * [What can I do with Hooks that I couldn't with classes?](#what-can-i-do-with-hooks-that-i-couldnt-with-classes)
   * [How much of my React knowledge stays relevant?](#how-much-of-my-react-knowledge-stays-relevant)
   * [Should I use Hooks, classes, or a mix of both?](#should-i-use-hooks-classes-or-a-mix-of-both)
   * [Do Hooks cover all use cases for classes?](#do-hooks-cover-all-use-cases-for-classes)
@@ -51,10 +53,27 @@ This page answers some of the frequently asked questions about [Hooks](/docs/hoo
 
 ## Adoption Strategy
 
+### Which versions of React include Hooks?
+
+Starting with 16.8.0, React includes a stable implementation of React Hooks for:
+
+* React DOM
+* React DOM Server
+* React Test Renderer
+* React Shallow Renderer
+
+Note that **to enable Hooks, all React packages need to be 16.8.0 or higher**. Hooks won't work if you forget to update, for example, React DOM.
+
+React Native will fully support Hooks in its next stable release.
+
 ### Do I need to rewrite all my class components?
 
 No. There are [no plans](/docs/hooks-intro.html#gradual-adoption-strategy) to remove classes from React -- we all need to keep shipping products and can't afford rewrites. We recommend trying Hooks in new code.
 
+### What can I do with Hooks that I couldn't with classes?
+
+Hooks offer a powerful and expressive new way to reuse functionality between components. ["Building Your Own Hooks"](/docs/hooks-custom.html) provides a glimpse of what's possible. [This article](https://medium.com/@dan_abramov/making-sense-of-react-hooks-fdbde8803889) by a React core team member dives deeper into the new capabilities unlocked by Hooks.
+
 ### How much of my React knowledge stays relevant?
 
 Hooks are a more direct way to use the React features you already know -- such as state, lifecycle, context, and refs. They don't fundamentally change how React works, and your knowledge of components, props, and top-down data flow is just as relevant.
@@ -71,7 +90,7 @@ You can't use Hooks *inside* of a class component, but you can definitely mix cl
 
 Our goal is for Hooks to cover all use cases for classes as soon as possible. There are no Hook equivalents to the uncommon `getSnapshotBeforeUpdate` and `componentDidCatch` lifecycles yet, but we plan to add them soon.
 
-It is a very early time for Hooks, so some integrations like DevTools support or Flow/TypeScript typings may not be ready yet. Some third-party libraries might also not be compatible with Hooks at the moment.
+It is an early time for Hooks, and some third-party libraries might not be compatible with Hooks at the moment.
 
 ### Do Hooks replace render props and higher-order components?
 
@@ -85,7 +104,7 @@ In the future, new versions of these libraries might also export custom Hooks su
 
 ### Do Hooks work with static typing?
 
-Hooks were designed with static typing in mind. Because they're functions, they are easier to type correctly than patterns like higher-order components. We have reached out both to Flow and TypeScript teams in advance, and they plan to include definitions for React Hooks in the future.
+Hooks were designed with static typing in mind. Because they're functions, they are easier to type correctly than patterns like higher-order components. The latest Flow and TypeScript React definitions include support for React Hooks.
 
 Importantly, custom Hooks give you the power to constrain React API if you'd like to type them more strictly in some way. React gives you the primitives, but you can combine them in different ways than what we provide out of the box.
 

content/docs/hooks-intro.md

@@ -5,10 +5,10 @@ permalink: docs/hooks-intro.html
 next: hooks-overview.html
 ---
 
-*Hooks* are an upcoming feature that lets you use state and other React features without writing a class. They're currently in React v16.8.0-alpha.1.
+*Hooks* are a new addition in React 16.8. They let you use state and other React features without writing a class.
 
 ```js{4,5}
-import { useState } from 'react';
+import React, { useState } from 'react';
 
 function Example() {
   // Declare a new state variable, which we'll call "count"
@@ -29,6 +29,10 @@ This new function `useState` is the first "Hook" we'll learn about, but this exa
 
 **You can start learning Hooks [on the next page](/docs/hooks-overview.html).** On this page, we'll continue by explaining why we're adding Hooks to React and how they can help you write great applications.
 
+>Note
+>
+>React 16.8.0 is the first release to support Hooks. When upgrading, don't forget to update all packages, including React DOM. React Native will support Hooks in the next stable release.
+
 ## Video Introduction
 
 At React Conf 2018, Sophie Alpert and Dan Abramov introduced Hooks, followed by Ryan Florence demonstrating how to refactor an application to use them. Watch the video here:
@@ -99,6 +103,10 @@ Finally, there is no rush to migrate to Hooks. We recommend avoiding any "big re
 
 We intend for Hooks to cover all existing use cases for classes, but **we will keep supporting class components for the foreseeable future.** At Facebook, we have tens of thousands of components written as classes, and we have absolutely no plans to rewrite them. Instead, we are starting to use Hooks in the new code side by side with classes.
 
+## Frequently Asked Questions
+
+We've prepared a [Hooks FAQ page](/docs/hooks-faq.html) that answers the most common questions about Hooks.
+
 ## Next Steps
 
 By the end of this page, you should have a rough idea of what problems Hooks are solving, but many details are probably unclear. Don't worry! **Let's now go to [the next page](/docs/hooks-overview.html) where we start learning about Hooks by example.**