Uh oh!
There was an error while loading. Please reload this page.
Update Developer Guide on SSR - #1570
Merged
Merged
Conversation
jonahtanjz
approved these changes
Jun 3, 2021
jonahtanjz
left a comment
Contributor
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
reviewed
Jun 5, 2021
ang-zeyu
left a comment
Contributor
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. |
| 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. | ||
Contributor
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.
Contributor
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. |
| 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: |
Contributor
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). |
Contributor
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)
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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: ☑️