diff --git a/cspell-wordlist.txt b/cspell-wordlist.txt index 785969053..090262807 100644 --- a/cspell-wordlist.txt +++ b/cspell-wordlist.txt @@ -30,6 +30,7 @@ prerenders proxied pseudocode runtimes +shadowrootmode sourcemaps templating transpiles diff --git a/docs/guides/hydrate-app.md b/docs/guides/hydrate-app.md index d02fe0b1b..37fd5c7af 100644 --- a/docs/guides/hydrate-app.md +++ b/docs/guides/hydrate-app.md @@ -37,14 +37,10 @@ After publishing your component library, you can import the hydrate app into your server's code like this: ```javascript -import { hydrateDocument } from 'yourpackage/hydrate'; +import { hydrateDocument, renderToString, streamToString } from 'yourpackage/hydrate'; ``` -The hydrate app module exports two functions, `hydrateDocument` and -`renderToString`. `hydrateDocument` takes a -[document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument) as -its input while `renderToString` takes a raw HTML string. Both functions return -a Promise which wraps a result object. +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 @@ -97,21 +93,156 @@ the hydrated HTML can be found under the `html` property. *Example taken from Ionic Core* ```javascript -const results = await hydrate.renderToString(srcHtml, { - prettyHtml: true, - removeScripts: true -}); +const results = await hydrate.renderToString( + ``, + { + fullDocument: false, + serializeShadowRoot: true, + prettyHtml: true, + } +); console.log(results.html); +/** + * outputs: + * ```html + * + * + * + * + * ``` + */ ``` #### renderToString Options - - `approximateLineWidth` - number - - `prettyHtml` - boolean - - `removeAttributeQuotes` - boolean - - `removeBooleanAttributeQuotes` - boolean - - `removeEmptyAttributes` - boolean - - `removeHtmlComments` - boolean - - `afterHydrate` - boolean - - `beforeHydrate` - boolean +##### `approximateLineWidth` + +__Type:__ `number` + +Determines when line breaks are being set when serializing the component. + +##### `prettyHtml` + +__Default:__ `false` + +__Type:__ `boolean` + +If set to `true` it prettifies the serialized HTML code, intends elements and escapes text nodes. + +##### `removeAttributeQuotes` + +__Type:__ `boolean` + +__Default:__ `false` + +If set to `true` it removes attribute quotes when possible, e.g. replaces `someAttribute="foo"` to `someAttribute=foo`. + +##### `removeEmptyAttributes` + +__Type:__ `boolean` + +__Default:__ `true` + +If set to `true` it removes attribute that don't have values, e.g. remove `class=""`. + +##### `removeHtmlComments` + +__Type:__ `boolean` + +__Default:__ `false` + +If set to `true` it removes any abundant HTML comments. Stencil still requires to insert hydration comments to be able to reconcile the component. + +##### `beforeHydrate` + +__Type:__ `(document: Document, url: URL) => | Promise` + +Allows to modify the document and all its containing components to be modified before the hydration process starts. + +##### `afterHydrate` + +__Type:__ `(document: Document, url: URL, results: PrerenderUrlResults) => | Promise` + +Allows to modify the document and all its containing components after the component was rendered in the virtual DOM and before the serialization process starts. + +##### `serializeShadowRoot` + +__Default:__ `false` + +__Type:__ `boolean` + +If set to `true` Stencil will render a component defined with a `shadow: true` flag into a [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom), e.g.: + +```javascript +const results = await hydrate.renderToString( + ``, + { + fullDocument: false, + serializeShadowRoot: true, + prettyHtml: true, + } +); + +console.log(results.html); +/** + * outputs: + * ```html + * + * + * + * + * ``` + */ +``` + +```javascript +const results = await hydrate.renderToString( + ``, + { + fullDocument: false, + serializeShadowRoot: false, + prettyHtml: true, + } +); + +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` + +__Default:__ `true` + +If set to `true`, Stencil will serialize a complete HTML document for a server to respond. If set to `false` it will only render the components within the given template.