Improve documentation for useSyncExternalStore #6530
Conversation
Size changes📦 Next.js Bundle Analysis for react-devThis analysis was generated by the Next.js Bundle Analysis action. 🤖 This PR introduced no changes to the JavaScript bundle! 🙌 |
There was a problem hiding this comment.
Hey @pwbriggs, thanks for the suggestion and your help elsewhere on the docs! I left some comments for improving this even more, let me know what you think!
| }; | ||
|
|
||
| console.log(object1 == object2); // false | ||
| ``` |
There was a problem hiding this comment.
Something is missing here that connects it back to why return {} is a new object every time, something like this:
This also applies to the return values of functions:
function getUser() {
return {
name: "John",
favoriteNumber: 42
};
}
const object1 = getUser();
const object2 = getUser();
console.log(object1 == object2); // falseAnd maybe add an example of hosting the object out to show how it doesn't change?
There was a problem hiding this comment.
The examples would be better as chat settings like in the explanations above rather than users.
There was a problem hiding this comment.
@rickhanlonii I'm not sure how I should change the code example. I want it to be clear to the reader that this isn't specific to getSnapshot handlers (we include examples of that above), but it needs to include returning an object from a function (like you said).
We also want to make it clear that the values of the retuned object are the same, but then it doesn't make sense why you would be comparing the returned values.
The best I can think of is something like this:
function getMathConstants() {
return {
pi: 3.14159,
e: 2.71828
}
}
let mathConstants1 = getMathConstants();
let mathConstants2 = getMathConstants();
console.log(mathConstants1 == mathConstants2);
// falseBut that makes very little sense. And, like you said, it should probably be related to the example chat app.
Any suggestions?
Update everything but the code example.
|
Hey @pwbriggs, unrelated to this PR, I can't find a way to contact you. Can you email me or DM me on twitter? I appreciate all you do on the docs and I'd like to upgrade your permissions to be a maintainer if you're interested :) |
|
Sure, thanks for the invitation! Do you have an email address you're willing to share? Do you have access to |
|
Same as my GH handle at gmail |
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Clarify the "I’m getting an error: “The result of getSnapshot should be cached” section of the
useSyncExternalStoreAPI reference documentation.I put some notes about why the documented error occurs in a
<DeepDive>section. It focuses on the details of comparison in JavaScript. I'm not sure if this is the intended use of deep dive sections (for example, how much prior knowledge about JavaScript do we assume the reader has? Who is the intended audience for the deep dive sections in the API reference? How well-known are the details of comparing objects in JavaScript?), but, in any case, I think this is at least an improvement.