Update Developer Guide on SSR #1570
Conversation
jonahtanjz
left a comment
jonahtanjz
left a comment
There was a problem hiding this comment.
Good job @wxwxwxwx9 👍 I feel it's clear and detailed. Thanks for working on this. LGTM!
ang-zeyu
left a comment
ang-zeyu
left a comment
There was a problem hiding this comment.
Sorry for the late review!
This generally looks good to me as well 👍
Several small suggestions we can deal with later:
|
|
||
| SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML. | ||
|
|
||
| During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR. |
There was a problem hiding this comment.
essentially diff -> compares
| During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR. | ||
|
|
||
| This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. | ||
|
|
There was a problem hiding this comment.
Could add an alert box here highlighting that this comparison dosen't execute in production vue build. Rather, if there are any runtime errors resulting from hydration errors, then full csr is re-executed.
There was a problem hiding this comment.
in case anyone tests this with production builds
| Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". | ||
|
|
||
| It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things: | ||
| 1) the state data are the same between client-side and server-side. |
There was a problem hiding this comment.
state data -> initial state
| 1) the state data are the same between client-side and server-side. | ||
| 2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified. | ||
|
|
||
| However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: |
There was a problem hiding this comment.
Slight reorganisation since both are actually html spec issues:
However
there are also some more specific rules that we should adhere to -> note that the HTML spec should be adhered to. Some common mistakes are as such:
- Having block-level elements within
<p>tag - Having unknown ...
| - Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag). | ||
| - Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). | ||
|
|
||
| Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely). |
There was a problem hiding this comment.
Could also add:
If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span)
3 participants
What is the purpose of this pull request?
With the SSR implementation in #1534, we should also update the developer guide to let contributors know what they should be aware of (regarding SSR) when making contributions to MarkBind.
Overview of changes:
Added a new section for SSR under
Designin the developer guide.Anything you'd like to highlight / discuss:
Testing instructions:
NIL
Proposed commit message: (wrap lines at 72 characters)
Update Developer Guide on SSR.
There are a few important information that contributors should
take note of regarding SSR (especially hydration issues).
Let's update the developer guide to include those information.
Checklist: ☑️