-
Notifications
You must be signed in to change notification settings - Fork 7.8k
Update docs for stable Hooks #1593
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
08b6e4b
4d61b4a
f510e11
9d62821
eaefc81
57138d7
5da272a
e9081c7
d15ec6e
37d46dd
ee5fea9
e301239
2fd487e
ed6e711
0d89570
95258c0
e5a987b
d460a9b
f9f0d66
d97cdca
601c016
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
- Loading branch information
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -38,22 +38,43 @@ Note that **to enable Hooks, all React packages need to be 16.8.0 or higher**. H | |
|
|
||
| ## 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 recommend using a new [lint rule](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. | ||
| 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. Our goal is to empower the React community to write components and Hooks that deliver great user and developer experience. We can't wait to see what you'll create next! | ||
| 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: | ||
|
|
@@ -77,6 +98,37 @@ We also provide UMD builds of React via a CDN: | |
|
|
||
| Refer to the documentation for [detailed installation instructions](/docs/installation.html). | ||
|
|
||
| ### ESLint Plugin for React Hooks | ||
|
|
||
| >Note | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. +As mentioned above, we strongly recommend using the `eslint-plugin-react-hooks` lint rule. |
||
| > | ||
| >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 | ||
|
|
@@ -92,6 +144,7 @@ Refer to the documentation for [detailed installation instructions](/docs/instal | |
| * 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)) | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll take the opportunity to ask a question if you don't mind. I noticed that hooks' values aren't easily editable like class properties in the DevTools, which was a surprise for me.
Although they could be considered "fully-supported" in the sense of what's possible to do in regards to implementation details, I'd think the passage also implies feature-parity with the way people are used to interact with class components.
The way the sentence is structured implies a solved problem. Is it the case? Or will hooks' values also be as flexible in the future?