From 015caa27e566ad910843d3088fc173a477b215aa Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 19 Aug 2024 08:16:07 -0700 Subject: [PATCH] docs(hydrate): better docs around hydrateDocument and renderToString (#1470) --- docs/guides/hydrate-app.md | 62 ++++++++++++------- .../version-v4.20/guides/hydrate-app.md | 16 ++--- 2 files changed, 46 insertions(+), 32 deletions(-) diff --git a/docs/guides/hydrate-app.md b/docs/guides/hydrate-app.md index 37fd5c7af..c1d449864 100644 --- a/docs/guides/hydrate-app.md +++ b/docs/guides/hydrate-app.md @@ -37,26 +37,24 @@ After publishing your component library, you can import the hydrate app into your server's code like this: ```javascript -import { hydrateDocument, renderToString, streamToString } from 'yourpackage/hydrate'; +import { createWindowFromHtml, hydrateDocument, renderToString, streamToString } from 'yourpackage/hydrate'; ``` The hydrate app module exports 3 functions, `hydrateDocument`, `renderToString` and `streamToString`. `hydrateDocument` takes a [document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument) as its input while `renderToString` as well as `streamToString` takes a raw HTML string. While `hydrateDocument` and `renderToString` return a Promise which wraps a result object, `streamToString` returns a [`Readable`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) stream that can be passed into a server response. ### hydrateDocument -You can use `hydrateDocument` as a part of your server's response logic before -serving the web page. `hydrateDocument` takes two arguments, a -[document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument) and a -config object. The function returns a promise with the hydrated results, with -the hydrated HTML under the `html` property. +You can use `hydrateDocument` as a part of your server's response logic before serving the web page. `hydrateDocument` takes two arguments, a [document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument) and a config object. The function returns a promise with the hydrated results, with the hydrated HTML under the `html` property. *Example taken from Ionic Angular server* - ```javascript -import { hydrateDocument } from 'yourpackage/hydrate'; + ```ts +import { hydrateDocument, createWindowFromHtml } from 'yourpackage/hydrate'; -export function hydrateComponents(doc) { - return hydrateDocument(doc) +export function hydrateComponents(template: string) { + const win = createWindowFromHtml(template, Math.random().toString()) + + return hydrateDocument(win.document) .then((hydrateResults) => { // execute logic based on results console.log(hydrateResults.html); @@ -65,6 +63,34 @@ export function hydrateComponents(doc) { } ``` +You can call the `hydrateComponents` function from your Node.js server, e.g.: + +```ts +import Koa from 'koa'; + +const app = new Koa(); +app.use(async (ctx) => { + const res = await hydrateComponents(` + + + + + Document + + + + + + +`) + ctx.body = res +}) +``` + +Please note that Stencil injects scoped component styles immediately after `` tags with a `rel="preconnect"` attribute, but before your custom styles. This setup allows you to define custom styles for your components effectively. + #### hydrateDocument Options - `canonicalUrl` - string @@ -176,7 +202,7 @@ Allows to modify the document and all its containing components after the compon ##### `serializeShadowRoot` -__Default:__ `false` +__Default:__ `true` __Type:__ `boolean` @@ -212,9 +238,11 @@ console.log(results.html); */ ``` +When set to `false`, the component renders with its light DOM but delays hydration until runtime. + ```javascript const results = await hydrate.renderToString( - ``, + `👋`, { fullDocument: false, serializeShadowRoot: false, @@ -226,19 +254,11 @@ console.log(results.html); /** * outputs: * ```html - * - * - *
- * - * Hello, World! I'm Stencil 'Don't call me a framework' JS - *
- * + * 👋 * ``` */ ``` -If set to `false` it renders the component as scoped component. - ##### `fullDocument` __Type:__ `boolean` diff --git a/versioned_docs/version-v4.20/guides/hydrate-app.md b/versioned_docs/version-v4.20/guides/hydrate-app.md index 37fd5c7af..9cdfdaf9b 100644 --- a/versioned_docs/version-v4.20/guides/hydrate-app.md +++ b/versioned_docs/version-v4.20/guides/hydrate-app.md @@ -176,7 +176,7 @@ Allows to modify the document and all its containing components after the compon ##### `serializeShadowRoot` -__Default:__ `false` +__Default:__ `true` __Type:__ `boolean` @@ -212,9 +212,11 @@ console.log(results.html); */ ``` +When set to `false`, the component renders with its light DOM but delays hydration until runtime. + ```javascript const results = await hydrate.renderToString( - ``, + `👋`, { fullDocument: false, serializeShadowRoot: false, @@ -226,19 +228,11 @@ console.log(results.html); /** * outputs: * ```html - * - * - *
- * - * Hello, World! I'm Stencil 'Don't call me a framework' JS - *
- * + * 👋 * ``` */ ``` -If set to `false` it renders the component as scoped component. - ##### `fullDocument` __Type:__ `boolean`