Add docs/hydration entry. (#22767)

- Update glossary.md, doc-links.yaml with links to new article.
gatsbyjs · Apr 6, 2020 · 0c77a62 · 0c77a62
1 parent 2bee16e
commit 0c77a62
Show file tree

Hide file tree

Showing 3 changed files with 56 additions and 1 deletion.
diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md
@@ -176,7 +176,7 @@ A hosting provider keeps a copy of your website or app and makes it accessible t
 
 A feature in use when you run `gatsby develop` that live updates your site on save of code in a text editor by automatically replacing modules, or chunks of code, in an open browser window.
 
-### Hydration
+### [Hydration](/docs/glossary/hydration/)
 
 Once a site has been [built](#build) by Gatsby and loaded in a web browser, [client-side](#client-side) JavaScript assets will download and turn the site into a full React application that can manipulate the [DOM](#dom). This process is often called re-hydration as it runs some of the same JavaScript code used to generate Gatsby pages, but this time with browser DOM APIs like `window` available.
 

diff --git a/docs/docs/glossary/hydration.md b/docs/docs/glossary/hydration.md
@@ -0,0 +1,53 @@
+---
+title: Hydration
+disableTableOfContents: true
+---
+
+Learn what _hydration_ means, and how Gatsby makes use of React's hydration features to build blazing fast websites and applications.
+
+## What is hydration?
+
+_Hydration_ is the process of using client-side JavaScript to add application state and interactivity to server-rendered HTML. It's a feature of [React](/docs/glossary/react/), one of the underlying tools that makes the Gatsby framework. Gatsby uses hydration to transform the static HTML created at [build time](/docs/glossary/build/) into a React application.
+
+A typical React application relies on client-side rendering. Instead of parsing HTML to create the [DOM](/docs/glossary#dom), client-side rendering uses JavaScript to create it. A minimal HTML document serves as the application container, and only contains links to the JavaScript and CSS necessary to render the application.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,user-scalable=yes" />
+    <title>ExampleApp</title>
+    <style>
+      body {
+        background: "images/loader.svg" center no-repeat;
+      }
+    </style>
+  </head>
+  <body>
+    <!-- This empty element becomes the application's container -->
+    <main id="root"></main>
+    <script type="text/javascript" src="./js/main.0932cd15.js"></script>
+  </body>
+</html>
+```
+
+With client-side rendering, most actions trigger local DOM updates instead of network requests. Clicking a clicking a navigation link builds the requested page on the client instead of requesting it from the server. Because they make fewer network requests, applications rendered in the browser provide a blazing-fast user experience &mdash; after the initial download.
+
+That's the drawback to client-side rendering: none of your site's content is visible or interactive until the client downloads JavaScript and builds the DOM. However, not all clients can construct a DOM. For example, client-side rendering can prevent search engine and social media crawlers from consuming and indexing your site's URLs. Browser users, on the other hand, may see a blank page or loading image while your JavaScript bundle downloads and executes.
+
+[Server-side rendering](/docs/glossary/server-side-rendering/) makes HTML available to the client _before_ JavaScript loads. Your site visitors can see and read your content even if it is not fully interactive. Server rendering eliminates the blank page problem. Rendered HTML also makes it easier for search engine and social media crawlers to consume your site. Of course, server-side rendering also has a drawback: every URL request requires another round trip to the server.
+
+Hydration lets us take a hybrid approach.
+
+> **Note:** You'll sometimes see developers use _re-hydration_ used instead of _hydration_. They're interchangeable.
+
+Gatsby's build process uses [Node.js](/docs/glossary/node/) and [`ReactDOMServer`](https://reactjs.org/docs/react-dom-server.html) to create two different versions of your site. Each URL is available as both a static HTML page, and as a JavaScript component.
+
+When a visitor requests their first URL from your site, the response contains static HTML along with linked JavaScript, CSS, and images. React then takes over and _hydrates_ that HTML. React adds event listeners to the DOM created during HTML parsing, and turns your site into a full React application. Subsequent page requests are DOM updates managed by React.
+
+### Learn More
+
+- [Understanding React Hydration](https://www.gatsbyjs.org/docs/react-hydration/) from the Gatsby docs
+- [ReactDOM.hydrate()](https://reactjs.org/docs/react-dom.html#hydrate) from the React API Reference
+- [Rendering on the Web](https://developers.google.com/web/updates/2019/02/rendering-on-the-web) from Google
diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
@@ -767,6 +767,8 @@
           link: /docs/glossary/headless-cms/
         - title: Headless WordPress
           link: /docs/glossary/headless-wordpress/
+        - title: Hydration
+          link: /docs/glossary/hydration/
         - title: JAMStack
           link: /docs/glossary/jamstack/
         - title: Markdown