From 0aadd5ad59fd21beccee686b154836ac209a3a1c Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sun, 30 May 2021 19:30:28 +0800 Subject: [PATCH 1/4] Create new page for SSR --- docs/_markbind/layouts/devGuide.md | 1 + docs/devGuide/design/serverSideRendering.md | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 docs/devGuide/design/serverSideRendering.md diff --git a/docs/_markbind/layouts/devGuide.md b/docs/_markbind/layouts/devGuide.md index 8a1546fbe3..281464f1f3 100644 --- a/docs/_markbind/layouts/devGuide.md +++ b/docs/_markbind/layouts/devGuide.md @@ -13,6 +13,7 @@ * Design :expanded: * [Project Structure]({{baseUrl}}/devGuide/design/projectStructure.html) * [Architecture]({{baseUrl}}/devGuide/design/architecture.html) + * [Server Side Rendering]({{baseUrl}}/devGuide/design/serverSideRendering.html) * [Writing Plugins]({{baseUrl}}/devGuide/writingPlugins.html) * [Project management]({{baseUrl}}/devGuide/projectManagement.html) * Appendices :expanded: diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md new file mode 100644 index 0000000000..12828ca5c6 --- /dev/null +++ b/docs/devGuide/design/serverSideRendering.md @@ -0,0 +1,17 @@ +{% set title = "Server Side Rendering" %} +{{ title }} + + + title: "{{ title }}" + layout: devGuide.md + pageNav: default + + +# {{ title }} + +
+ +This page describes how server-side rendering is implemented in MarkBind. +
+ + From e7b5d994bdcc8903146e359789af4f758cb18ebe Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sun, 30 May 2021 20:58:59 +0800 Subject: [PATCH 2/4] Initial write-up --- docs/devGuide/design/serverSideRendering.md | 33 ++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 12828ca5c6..813fc583d6 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -11,7 +11,38 @@
-This page describes how server-side rendering is implemented in MarkBind. +MarkBind makes use of 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 developing.
+## What is Server-side Rendering and Why? + +In MarkBind's context, Server-side Rendering 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. + +## Client-side Hydration + +Server-side Rendering 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`s 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 Client-side Rendering. + +This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. + +## Avoiding Hydration Issue + +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. +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). +- 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). + +## Learning more about SSR in MarkBind and Debugging Hydration Issue + From 6f8193a2450705c287f78d516a59d5df2a57c605 Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sun, 30 May 2021 22:39:07 +0800 Subject: [PATCH 3/4] More write-up --- docs/devGuide/design/serverSideRendering.md | 39 ++++++++++++++++++--- 1 file changed, 34 insertions(+), 5 deletions(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 813fc583d6..92e0ecf49e 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -11,11 +11,36 @@

-MarkBind makes use of server-side rendering (SSR) for its pages. To ensure SSR works properly, there are certain rules that developers should adhere to. +MarkBind makes use of 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 developing.
+## Pre-requisite Knowledge + +To deal with SSR, it is important to first have a good understanding of two things: 1) Vue, 2) MarkBind's Packages. + +### Understanding Vue + +Here are some things that you should have some knowledge of: +- What is a Vue instance? +- What does it mean to compile Vue? +- What are render functions? +- Are there any differences between compiling Vue on client-side versus server-side? +- What is the difference between compiling and rendering? + +### MarkBind's Packages + +There are four packages in MarkBind's codebase: +1. cli +2. core +3. core-web +4. vue-components + +You may refer to MarkBind's [project structure](projectStructure.md) to get a better understanding of how the packages work together. + ## What is Server-side Rendering and Why? In MarkBind's context, Server-side Rendering 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). @@ -30,6 +55,14 @@ During the hydration process, Vue essentially `diff`s your SSR HTML markup again This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. +## 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). + +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 universal application concept as much as possible. + ## Avoiding Hydration Issue Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". @@ -42,7 +75,3 @@ However, beyond achieving a "universal application", there are also some more sp - 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). - -## Learning more about SSR in MarkBind and Debugging Hydration Issue - - From 4050f5380040626d4388b5bc86419e9815a683c6 Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sun, 30 May 2021 22:45:14 +0800 Subject: [PATCH 4/4] Touch up --- docs/devGuide/design/serverSideRendering.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 92e0ecf49e..371573050b 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -11,20 +11,22 @@
-MarkBind makes use of server-side rendering (SSR) for its pages. +MarkBind makes use of 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 developing. +This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind.
## Pre-requisite Knowledge -To deal with SSR, it is important to first have a good understanding of two things: 1) Vue, 2) MarkBind's Packages. +To deal with SSR, it is important to first have a good understanding of two things: +1. Vue +2. MarkBind's Packages ### Understanding Vue -Here are some things that you should have some knowledge of: +Here is a short list of questions to check your understanding of Vue: - What is a Vue instance? - What does it mean to compile Vue? - What are render functions? @@ -43,15 +45,15 @@ You may refer to MarkBind's [project structure](projectStructure.md) to get a be ## What is Server-side Rendering and Why? -In MarkBind's context, Server-side Rendering 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). +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. +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). ## Client-side Hydration -Server-side Rendering 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. +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`s 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 Client-side Rendering. +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. @@ -61,11 +63,12 @@ When hydration fails, on top of the wasted time and effort in executing SSR, we 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 universal application concept as much as possible. +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. ## Avoiding Hydration Issue 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. 2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.