Server Side Rendering
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 caveats that developers should take note of when contributing to MarkBind.
To deal with SSR, it is important to first have a good understanding of two things:
Here is a short list of questions to check your understanding of Vue:
If there are any doubts regarding the questions above, here are some good resources to refer to:
There are four packages in MarkBind's codebase:
You may refer to MarkBind's project structure to get a better understanding of how the packages work together.
In MarkBind's context, SSR refers to the generation of proper HTML strings from Vue components on the server (core library) instead of shifting that responsibility to the client-side (browser).
The main motivation that we had for introducing SSR into MarkBind is to enhance user experience by resolving the unsightly issue of Flash-of-Unstyled-Content (FOUC), which occurs due to our reliance on Client-side Rendering (CSR).
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 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.
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).
Fortunately, even if we face hydration issues and execute full CSR, the FOUC problem will still be resolved nonetheless. The reason for this is because the SSR HTML markup should resemble the CSR HTML markup to a large extent.
Supposedly, hydration issues typically occurs due to minor differences between client-side rendered virtual DOM tree and the server-rendered content. Of course, this is assuming that we are adhering to the concept of "universal application" as much as possible, which will be explained in the following section.
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:
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to.
Some common mistakes are as such:
<p> tagv-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.
Please help extend it when violations that cause hydration on browsers are spotted.
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).