Update docs for stable Hooks #1593
Conversation
gaearon
force-pushed
the
hooks-stable
branch
2 times, most recently
from
1b9bd9b
to
b898edf
Compare
|
Deploy preview for reactjs ready! Built with commit 82cd8ddfba1dab6960684a5fce27f6fb05b9173f |
|
Deploy preview for reactjs ready! Built with commit b898edfc8b1ca941a31f354eea3601ca5c9901fa |
|
Deploy preview for reactjs ready! Built with commit 601c016 |
| * [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) |
There was a problem hiding this comment.
I think I already edited that?
There was a problem hiding this comment.
I'm sorry just saw that. I'll close that issue
|
Pushed blog post draft. (Note: DON'T MERGE UNTIL BLOG POST DATE IS SET TO THE REAL ONE) |
|
|
||
| ## 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. |
There was a problem hiding this comment.
How about:
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.
CRA soon? Why not now?
There was a problem hiding this comment.
Didn't want to make it a release blocker because we also wanted to get facebook/create-react-app#6219 in and possibly facebook/react#14636. But maybe we should just split those.
|
|
||
| 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! |
There was a problem hiding this comment.
"Our goal…" is a little fluffy. I might write:
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.
(Take or leave, I don't mind the current one either.)
There was a problem hiding this comment.
I guess I was trying to say our job is to focus on the primitives
|
|
||
| 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. | ||
|
|
||
| ## Installation |
There was a problem hiding this comment.
Add lint rule to this section?
| ### 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 [#13968](https://github.com/facebook/react/pull/13968)) |
There was a problem hiding this comment.
what about facebook/react#14040 🙃
|
I added more details to changelog. Practically these PRs can be considered part of Hooks but I figured alpha users might appreciate calling out the changes. |
|
|
||
| ## 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. |
There was a problem hiding this comment.
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?
|
|
||
| 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`. |
There was a problem hiding this comment.
do we need to mention 16.7-.1? IIRC it didn't have hooks (oops)
|
|
||
| **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: |
There was a problem hiding this comment.
Can we remind people no "real" breaking changes? Maybe:
Like all minor releases, 16.8.0 contains no breaking changes relative to previous 16.x releases (16.0.0 through 16.7.0). For devs currently using an alpha release of React with Hooks, please note this list of the breaking changes we've made since the first alpha.
OR ALTERNATIVELY:
Can we move this to the very end of the post (after ## Changelog) and do like:
Thanks
...
Hooks Changelog Since Alpha Versions
The above changelog contains all notable changes since our last stable release (16.7.0). [As with all our minor releases](versioning policy), none of the changes break backwards compatibility.
If you're currently using Hooks from an alpha build of React, note that this release does contain some small breaking changes to Hooks. We don't recommend depending on alphas in production code. We publish them so we can make changes in response to community feedback before the API is stable.
Here are all breaking changes to Hooks that have been made since the first alpha release:
I think I like that better. 70% of readers probably won't need the section so it's better to move it later IMO.
|
|
||
| ### ESLint Plugin for React Hooks | ||
|
|
||
| >Note |
There was a problem hiding this comment.
+As mentioned above, we strongly recommend using the `eslint-plugin-react-hooks` lint rule.
+
|
|
||
| ## 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. |
There was a problem hiding this comment.
nit: "with your existing code" -> "with existing code" for consistency with the first half of the sentence (and brevity)
|
|
||
| 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.** |
There was a problem hiding this comment.
can we include a version number?
|
|
||
| **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. |
There was a problem hiding this comment.
It was actually accidentally merged early and is already available in @types/react@16.8.1 😅
Fortunately the only part that is not compatible for current alpha users is the 3rd argument to useReduce.
There was a problem hiding this comment.
To clarify, the DefinitelyTyped publish bot does an auto-publish, with a patch version bump, every time a PR is merged. There were 2 PRs to update the API so the first publish to have both was 16.8.1.
content/docs/hooks-reference.md
Outdated
|
|
||
| >Note | ||
| > | ||
| >React doesn’t use the `state = initialState` argument convention popularized by Redux. The initial value sometimes needs to depend on props and so is specified from the Hook call instead. If you feel strongly about this, you can write `state = initialState` both in the reducer and inside the `useReducer` destructuring assignment, but it's not encouraged. |
There was a problem hiding this comment.
FWIW I found this very hard to parse due to my unfamiliarity. Maybe…
To specify initial state, React doesn't use the default arguments pattern
function reducer(action, state = {count: 0})popularized by Redux.
you can write
state = initialStateboth in the reducer and inside theuseReducerdestructuring assignment
can you not put it only in the reducer and let the initial state default to undefined? why?
| @@ -322,6 +323,22 @@ function ScrollView({row}) { | |||
|
|
|||
| This might look strange at first, but an update during rendering is exactly what `getDerivedStateFromProps` has always been like conceptually. | |||
|
|
|||
| ### Is there something like forceUpdate? | |||
|
|
|||
| Both `useState` and `useReducer` Hooks [bail out of updates](/docs/hooks-reference.html#bailing-out-of-a-state-update) if the next value is the same as the previous one. Mutating state in place and calling `setState` will not cause a re-render. | |||
There was a problem hiding this comment.
"bail out" feels jargony – how do you feel about "skip rerendering"?
| @@ -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 | |||
There was a problem hiding this comment.
What about a plugin that automatically provides hooks with the right arguments? Such as useMemo and useCallback. It's also mentioned in the docs:
Note
The array of inputs is not passed as arguments to the callback. Conceptually, though, that’s what they represent: every value referenced inside the callback should also appear in the inputs array. In the future, a sufficiently advanced compiler could create this array automatically.
Check out a plugin of mine (still experimental): https://github.com/DAB0mB/babel-plugin-react-persist Would be nice to add it to the docs rather than people just searching around, or even worse, not using hooks when necessary.
|
Dan's gone for the day and we don't have write access to his repo so I've forked and opened a new PR #1629 |
Work in progress. Don't merge before the release.
ALSO DON'T MERGE UNTIL BLOG POST DATE IS SET TO THE REAL ONE