Update docs for stable Hooks

Author: gaearon

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* 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* 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* 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* 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.**

content/docs/hooks-overview.md

@@ -6,7 +6,7 @@ next: hooks-state.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* let you use state and other React features without writing a class.
 
 Hooks are [backwards-compatible](/docs/hooks-intro.html#no-breaking-changes). This page provides an overview of Hooks for experienced React users. This is a fast-paced overview. If you get confused, look for a yellow box like this:
 
@@ -21,7 +21,7 @@ Hooks are [backwards-compatible](/docs/hooks-intro.html#no-breaking-changes). Th
 This example renders a counter. When you click the button, it increments the value:
 
 ```js{1,4,5}
-import { useState } from 'react';
+import React, { useState } from 'react';
 
 function Example() {
   // Declare a new state variable, which we'll call "count"
@@ -77,7 +77,7 @@ The Effect Hook, `useEffect`, adds the ability to perform side effects from a fu
 For example, this component sets the document title after React updates the DOM:
 
 ```js{1,6-10}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function Example() {
   const [count, setCount] = useState(0);
@@ -104,7 +104,7 @@ When you call `useEffect`, you're telling React to run your "effect" function af
 Effects may also optionally specify how to "clean up" after them by returning a function. For example, this component uses an effect to subscribe to a friend's online status, and cleans up by unsubscribing from it:
 
 ```js{10-16}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function FriendStatus(props) {
   const [isOnline, setIsOnline] = useState(null);
@@ -181,7 +181,7 @@ Earlier on this page, we introduced a `FriendStatus` component that calls the `u
 First, we'll extract this logic into a custom Hook called `useFriendStatus`:
 
 ```js{3}
-import { useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 
 function useFriendStatus(friendID) {
   const [isOnline, setIsOnline] = useState(null);

content/docs/hooks-reference.md

@@ -6,7 +6,7 @@ prev: hooks-custom.html
 next: hooks-faq.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* let you use state and other React features without writing a class.
 
 This page describes the APIs for the built-in Hooks in React.
 
@@ -367,15 +367,15 @@ useDebugValue(value)
 
 `useDebugValue` can be used to display a label for custom hooks in React DevTools.
 
-For example, consider the `useFriendStatus` custom hook described in ["Building Your Own Hooks"](/docs/hooks-custom.html):
+For example, consider the `useFriendStatus` custom Hook described in ["Building Your Own Hooks"](/docs/hooks-custom.html):
 
 ```js{6-8}
 function useFriendStatus(friendID) {
   const [isOnline, setIsOnline] = useState(null);
 
   // ...
 
-  // Show a label in DevTools next to this hook
+  // Show a label in DevTools next to this Hook
   // e.g. "FriendStatus: Online"
   useDebugValue(isOnline ? 'Online' : 'Offline');
 
@@ -385,15 +385,16 @@ function useFriendStatus(friendID) {
 
 > Tip
 >
-> We don't recommend adding debug values to every custom hook. It's most valuable for custom hooks that are part of shared libraries.
+> We don't recommend adding debug values to every custom Hook. It's most valuable for custom Hooks that are part of shared libraries.
 
 #### Defer formatting debug values
 
-In some cases formatting a value for display might be an expensive operation. It's also unnecessary unless a hook is actually inspected.
+In some cases formatting a value for display might be an expensive operation. It's also unnecessary unless a Hook is actually inspected.
 
-For this reason `useDebugValue` accepts a formatting function as an optional second parameter. This function is only called if the hooks is inspected. It receives the debug value as a parameter and should return a formatted display value.
+For this reason `useDebugValue` accepts a formatting function as an optional second parameter. This function is only called if the Hooks are inspected. It receives the debug value as a parameter and should return a formatted display value.
+
+For example a custom Hook that returned a `Date` value could avoid calling the `toDateString` function unnecessarily by passing the following formatter:
 
-For example a custom hook that returned a `Date` value could avoid calling the `toDateString` function unnecessarily by passing the following formatter:
 ```js
 useDebugValue(date, date => date.toDateString());
 ```

content/docs/hooks-rules.md

@@ -6,7 +6,7 @@ next: hooks-custom.html
 prev: hooks-effect.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* let you use state and other React features without writing a class.
 
 Hooks are JavaScript functions, but you need to follow two rules when using them. We provide a [linter plugin](https://www.npmjs.com/package/eslint-plugin-react-hooks) to enforce these rules automatically:
 
@@ -28,7 +28,7 @@ By following this rule, you ensure that all stateful logic in a component is cle
 We released an ESLint plugin called [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) that enforces these two rules. You can add this plugin to your project if you'd like to try it:
 
 ```bash
-npm install eslint-plugin-react-hooks@next
+npm install eslint-plugin-react-hooks
 ```
 
 ```js

content/docs/hooks-state.md

@@ -6,12 +6,12 @@ next: hooks-effect.html
 prev: 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* let you use state and other React features without writing a class.
 
 The [previous page](/docs/hooks-intro.html) introduced Hooks with this example:
 
 ```js{4-5}
-import { useState } from 'react';
+import React, { useState } from 'react';
 
 function Example() {
   // Declare a new state variable, which we'll call "count"
@@ -91,7 +91,7 @@ Hooks **don't** work inside classes. But you can use them instead of writing cla
 Our new example starts by importing the `useState` Hook from React:
 
 ```js{1}
-import { useState } from 'react';
+import React, { useState } from 'react';
 
 function Example() {
   // ...
@@ -123,7 +123,7 @@ class Example extends React.Component {
 In a function component, we have no `this`, so we can't assign or read `this.state`. Instead, we call the `useState` Hook directly inside our component:
 
 ```js{4,5}
-import { useState } from 'react';
+import React, { useState } from 'react';
 
 function Example() {
   // Declare a new state variable, which we'll call "count"
@@ -139,7 +139,7 @@ function Example() {
 Now that we know what the `useState` Hook does, our example should make more sense:
 
 ```js{4,5}
-import { useState } from 'react';
+import React, { useState } from 'react';
 
 function Example() {
   // Declare a new state variable, which we'll call "count"
@@ -196,7 +196,7 @@ Let's now **recap what we learned line by line** and check our understanding.
   But if GitHub got away with it for years we can cheat.
 -->
 ```js{1,4,9}
- 1:  import { useState } from 'react';
+ 1:  import React, { useState } from 'react';
  2:
  3:  function Example() {
  4:    const [count, setCount] = useState(0);

content/docs/nav.yml

@@ -104,7 +104,7 @@
       title: JS Environment Requirements
     - id: glossary
       title: Glossary
-- title: Hooks (Preview)
+- title: Hooks (New)
   isOrdered: true
   items:
       - id: hooks-intro