diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 371573050b..b53265964a 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -11,11 +11,11 @@
-MarkBind makes use of Server-side Rendering (SSR) for its pages. +MarkBind uses Server-side Rendering (SSR) for its pages. To ensure SSR works properly, there are certain rules that developers should adhere to. -This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. +This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind.
## Pre-requisite Knowledge @@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue: - Are there any differences between compiling Vue on client-side versus server-side? - What is the difference between compiling and rendering? -### MarkBind's Packages + + +If there are any doubts regarding the questions above, here are some good resources to refer to: + +- [Vue Official Documentation](https://vuejs.org/v2/guide) +- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU) + + +### Understanding MarkBind's Packages There are four packages in MarkBind's codebase: 1. cli @@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance 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 compares 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. + + +In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option). + + ## Penalties of Hydration Issue When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards). @@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c 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 initial state is 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: -- Do not violate HTML spec as much as possible (e.g. having block-level elements within `

` tag). +Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. + +Some common mistakes are as such: +- Having block-level elements within `

` 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). + + +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). + + 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).