From cc2cfb3cf25ba056424f1d70a624809a3231474e Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sat, 5 Jun 2021 22:34:14 +0800 Subject: [PATCH 1/6] Update SSR Guide --- docs/devGuide/design/serverSideRendering.md | 41 +++++++++++++++++---- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 371573050b..8fe8fbeb24 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 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,25 @@ 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. + + +There are some significant differences in how Vue **reports and handles hydration issues** between development and production builds. + +!!**Development Build**!! + +In development build, when Vue reports hydration issue, it will also provide information about the **exact mismatching node(s)** that is/are causing the hydration issue and inform the user that full CSR will be executed. Typically, it is very difficult to resolve hydration issues without the detailed error logs provided by the development build. + +!!**Production Build**!! + +In production build, when Vue reports hydration issue, it will only log a generic `"Failed to execute 'appendChild' on 'Node': This node type does not support this method"` error message and execute full CSR **silently**. We have even observed cases where the production build does not warn about existing hydration issues (silent failures). + +The above reasons are why 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 +93,15 @@ 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 states 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). +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). From 913485d5a5696bc753ed5fc686bac9509a7fafa4 Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sat, 5 Jun 2021 22:42:59 +0800 Subject: [PATCH 2/6] Add full stop --- docs/devGuide/design/serverSideRendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 8fe8fbeb24..e65e67e9dc 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -102,6 +102,6 @@ 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) +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). From ee47c97582c08a736c5605ee50f696c00e27303f Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sat, 5 Jun 2021 23:21:24 +0800 Subject: [PATCH 3/6] Update according to review --- docs/devGuide/design/serverSideRendering.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index e65e67e9dc..4ceac52b41 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -33,7 +33,7 @@ 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? - + If there are any doubts regarding the above, here are some good resources to refer to: @@ -65,9 +65,7 @@ During the hydration process, Vue essentially compares your SSR HTML markup agai This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. - - -There are some significant differences in how Vue **reports and handles hydration issues** between development and production builds. + !!**Development Build**!! @@ -93,7 +91,7 @@ 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 initial states 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. Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. @@ -102,6 +100,9 @@ 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). From c10347589567b1d0ddfb58f2dacb88d0aa9bf1da Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sun, 6 Jun 2021 11:34:24 +0800 Subject: [PATCH 4/6] Update serverSideRendering.md --- docs/devGuide/design/serverSideRendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 4ceac52b41..0484f4d9b2 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -69,7 +69,7 @@ This is known as "Hydration Issue" and it is one of the main challenges you will !!**Development Build**!! -In development build, when Vue reports hydration issue, it will also provide information about the **exact mismatching node(s)** that is/are causing the hydration issue and inform the user that full CSR will be executed. Typically, it is very difficult to resolve hydration issues without the detailed error logs provided by the development build. +In development build, when Vue reports hydration issue, it will also provide information about the **exact mismatching node(s)** that is/are causing the hydration issue and inform the user that full CSR will be executed. !!**Production Build**!! From b94306419e11aa1c6486c4cee62fa8ec49d2aa92 Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sun, 6 Jun 2021 13:31:32 +0800 Subject: [PATCH 5/6] Update serverSideRendering.md --- docs/devGuide/design/serverSideRendering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index 0484f4d9b2..dd322d3bce 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -35,7 +35,7 @@ Here is a short list of questions to check your understanding of Vue: -If there are any doubts regarding the above, here are some good resources to refer to: +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) From e5f5c3ad5356118966e20993c65633ea8f98eb65 Mon Sep 17 00:00:00 2001 From: wxwxwxwx9 <37920115+wxwxwxwx9@users.noreply.github.com> Date: Sun, 13 Jun 2021 10:07:59 +0800 Subject: [PATCH 6/6] Update serverSideRendering.md --- docs/devGuide/design/serverSideRendering.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md index dd322d3bce..b53265964a 100644 --- a/docs/devGuide/design/serverSideRendering.md +++ b/docs/devGuide/design/serverSideRendering.md @@ -65,17 +65,9 @@ During the hydration process, Vue essentially compares your SSR HTML markup agai This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. - + -!!**Development Build**!! - -In development build, when Vue reports hydration issue, it will also provide information about the **exact mismatching node(s)** that is/are causing the hydration issue and inform the user that full CSR will be executed. - -!!**Production Build**!! - -In production build, when Vue reports hydration issue, it will only log a generic `"Failed to execute 'appendChild' on 'Node': This node type does not support this method"` error message and execute full CSR **silently**. We have even observed cases where the production build does not warn about existing hydration issues (silent failures). - -The above reasons are why MarkBind **uses the development build by default** when you serve it in development mode (`-d` option). +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