Skip to content

Rework the Reactivity in Depth guide #934

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

Merged
merged 3 commits into from
Mar 18, 2021

Conversation

skirtles-code
Copy link
Contributor

@skirtles-code skirtles-code commented Mar 8, 2021

Description of Problem

Rendered: https://deploy-preview-934--vue-docs-next-preview.netlify.app/guide/reactivity.html

This started as an attempt to make some small tweaks to the Reactivity in Depth page. One tweak led to another and the end result is a significant reworking of the existing page. Much of the original structure remains but the diff will likely be a mess and I suggest that any reviewers approach it is as though it were a new page.

The biggest addition is a section about effects. The term 'effect' is used by subsequent pages in the guide (e.g. when discussing effect flush timing) but it wasn't really explained anywhere. It also appears in the animation at the bottom of this page. To my mind, this is a really important concept that forms a key part of the 'how reactivity works' puzzle. Once the concept is introduced I have then weaved it in where appropriate for the explanations that follow.

I have intentionally avoided using the term 'watcher'. Roughly speaking, a watcher is a combination of an effect and a separate callback function. I didn't want to introduce yet another concept on this page if I could help it and, hopefully, the explanations hold together without explicitly mentioning it.

Some of the later examples on the existing page use a function called reactive. However, it wasn't explicitly stated what that function was or how it related to the proxies shown earlier. While reactive and related functions are covered more thoroughly on the next page of the guide, I've tried to tie everything together a little more explicitly, before it gets used by those later examples.

The original proxy examples are mostly unchanged. I've renamed the parameters to avoid the names prop and key, as those terms have other connotations in Vue that could lead to confusion. I have also merged the first couple of proxy examples. Those two examples only differed by a single line of console logging, so a single example seemed sufficient.

There are various other changes throughout but I hope they are mostly self-explanatory. Please feel free to to ask for clarification about any of the changes I've made.

Additional Information

Copy link
Member

@NataliaTepluhina NataliaTepluhina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@skirtles-code great improvements! I've left a few non-blocking points for your consideration

@stafyniaksacha
Copy link

Is there a way to speak about ref and reactive functions here ?

@skirtles-code
Copy link
Contributor Author

@stafyniaksacha Those functions are covered more thoroughly on the next page of the guide. This page is trying to explain the underlying mechanics of how the reactivity system works rather than the specific details of how the individual functions behave.

Arguably some of the material on this page, e.g. the sections Proxied Objects and Proxy vs. original identity, stray a little from the central topic and should be moved elsewhere. Those sections already existed prior to my reworking so I've retained them for now but it may make sense to move them eventually, especially once we introduce a proper page of Vue 3 reactivity caveats (#849).

@skirtles-code skirtles-code marked this pull request as ready for review March 12, 2021 22:02
Copy link
Member

@bencodezen bencodezen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Solid improvements @skirtles-code! Going to go ahead and merge this because we can always iterate with another PR. Thanks for your work on this!

@bencodezen bencodezen merged commit 91a4425 into vuejs:master Mar 18, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
4 participants