From ccde5577f0afbc847319fc2dcaea465b948f214a Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Mon, 21 Oct 2024 18:07:20 -0700 Subject: [PATCH 01/10] docs: add better docs for SSR support --- docs/framework-integration/react.md | 70 ++++++++++++++++++++++++++-- docs/framework-integration/vue.md | 66 ++++++++++++++++++++++++++ docs/guides/server-side-rendering.md | 39 ++++++++++++++++ 3 files changed, 172 insertions(+), 3 deletions(-) create mode 100644 docs/guides/server-side-rendering.md diff --git a/docs/framework-integration/react.md b/docs/framework-integration/react.md index c805c541c..4c809a68f 100644 --- a/docs/framework-integration/react.md +++ b/docs/framework-integration/react.md @@ -16,6 +16,7 @@ This package includes an output target for code generation that allows developer - ♻️ Automate the generation of React component wrappers for Stencil components - 🌐 Generate React functional component wrappers with JSX bindings for custom events and properties - ⌨️ Typings and auto-completion for React components in your IDE +- 🚀 Support for Server Side Rendering (SSR) when used with frameworks like [Next.js](https://nextjs.org/) To generate these framework wrappers, Stencil provides an Output Target library called [`@stencil/react-output-target`](https://www.npmjs.com/package/@stencil/react-output-target) that can be added to your `stencil.config.ts` file. This also enables Stencil components to be used within e.g. Next.js or other React based application frameworks. @@ -129,10 +130,11 @@ In your `react-library` project, create a project specific `tsconfig.json` that "extends": "../../tsconfig.json", "compilerOptions": { "outDir": "./dist", - "lib": ["dom", "es2015"], - "module": "esnext", + "target": "ES2020", + "useDefineForClassFields": true, + "lib": ["ES2020", "DOM", "DOM.Iterable"], + "module": "ESNext", "moduleResolution": "bundler", - "target": "es2015", "skipLibCheck": true, "jsx": "react", "allowSyntheticDefaultImports": true, @@ -365,6 +367,68 @@ function App() { export default App; ``` +### Enable Server Side Rendering (SSR) + +If your React framework supports server side rendering, e.g. [Next.js](https://nextjs.org/) your Stencil components will get automatically server side rendered, if set up correctly. In order to enable this: + +1. Add a `dist-hydrate-script` output target to your `stencil.config.ts` if not already existing, e.g.: + ```ts title="stencil.config.ts" + import { Config } from '@stencil/core'; + + export const config: Config = { + outputTargets: [ + { + type: 'dist-hydrate-script', + dir: './hydrate', + }, + // ... + ] + }; + ``` + +2. Create an export for the compiled files within the `/hydrate` directory, e.g. + ```json + { + "name": "component-library", + ... + "exports": { + ... + "./hydrate": { + "types": "./hydrate/index.d.ts", + "import": "./hydrate/index.js", + "require": "./hydrate/index.cjs.js", + "default": "./hydrate/index.js" + }, + ... + }, + ... + } + ``` + +3. Set the `hydrateModule` in your React output target configuration, e.g. + ```ts + import { Config } from '@stencil/core'; + import { reactOutputTarget } from '@stencil/react-output-target'; + + export const config: Config = { + outputTargets: [ + reactOutputTarget({ + outDir: '../react-library/lib/components/stencil-generated/', + hydrateModule: 'component-library/hydrate' + }), + // ... + ] + }; + ``` + +That's it! Your Next.js application should now render a Declarative Shadow DOM on the server side which will get automatically hydrated once the React runtime initiates. + +:::cautions + +A Declarative Shadow DOM contains next to the HTML structure also all the CSS defined for the component. If you server side render a lot of small components that come with large amounts of CSS, it will drastically increase the initial page load time as the documented loaded by the browser increases in size. Make sure to keep the initial document size reasonable and aligned with your performance goals, server side rendering only the critical components needed to render the viewport and load the rest later on. + +::: + ## API ### esModule diff --git a/docs/framework-integration/vue.md b/docs/framework-integration/vue.md index 143a858a8..6a134b67e 100644 --- a/docs/framework-integration/vue.md +++ b/docs/framework-integration/vue.md @@ -348,6 +348,72 @@ In your page or component, you can now import and use your component wrappers: ``` +### Enable Server Side Rendering (SSR) + +If your Vue framework supports server side rendering, e.g. when using [Nuxt](https://nuxt.com/) your Stencil components will get automatically server side rendered, if set up correctly. In order to enable this: + +1. Add a `dist-hydrate-script` output target to your `stencil.config.ts` if not already existing, e.g.: + ```ts title="stencil.config.ts" + import { Config } from '@stencil/core'; + + export const config: Config = { + outputTargets: [ + { + type: 'dist-hydrate-script', + dir: './hydrate', + }, + // ... + ] + }; + ``` + +2. Create an export for the compiled files within the `/hydrate` directory, e.g. + ```json + { + "name": "component-library", + ... + "exports": { + ... + "./hydrate": { + "types": "./hydrate/index.d.ts", + "import": "./hydrate/index.js", + "require": "./hydrate/index.cjs.js", + "default": "./hydrate/index.js" + }, + ... + }, + ... + } + ``` + +3. Set the `hydrateModule` in your React output target configuration, e.g. + ```ts + import { Config } from '@stencil/core'; + import { vueOutputTarget } from '@stencil/vue-output-target'; + + export const config: Config = { + outputTargets: [ + vueOutputTarget({ + includeImportCustomElements: true, + includePolyfills: false, + includeDefineCustomElements: false, + componentCorePackage: 'component-library', + hydrateModule: 'component-library/hydrate', + proxiesFile: '../component-library-vue/src/index.ts', + }), + // ... + ] + }; + ``` + +That's it! Your Nuxt application should now render a Declarative Shadow DOM on the server side which will get automatically hydrated once the Vue runtime initiates. + +:::cautions + +A Declarative Shadow DOM contains next to the HTML structure also all the CSS defined for the component. If you server side render a lot of small components that come with large amounts of CSS, it will drastically increase the initial page load time as the documented loaded by the browser increases in size. Make sure to keep the initial document size reasonable and aligned with your performance goals, server side rendering only the critical components needed to render the viewport and load the rest later on. + +::: + ## API ### componentCorePackage diff --git a/docs/guides/server-side-rendering.md b/docs/guides/server-side-rendering.md new file mode 100644 index 000000000..5891e5e03 --- /dev/null +++ b/docs/guides/server-side-rendering.md @@ -0,0 +1,39 @@ +--- +title: Server Side Rendering +sidebar_label: Server Side Rendering +description: Server Side Rendering +slug: /server-side-rendering +--- + +# Server Side Rendering + +For React and Vue Output Targets Stencil has support for Server Side Rendering (SSR). If you use frameworks such as [Next.js](https://nextjs.org/) or [Nuxt](https://nuxt.com/) Stencil will automatically enhance the framework to allow render Stencil components on the server into a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom). + +You can find more information on how to setup SSR support for [React](/docs/react) and [Vue](/docs/vue) in their respective Output Target documentations. All interfaces related to rendering a Stencil component into a string are exported by the [Stencil Hyrdate Module](/docs/hydrate-app). + +## Tips & Tricks + +When server side rendering a component you may run into a few gotchas that may seem confusing when components don't appear as expected. Here are some important tips and tricks you should know to avoid these situations. + +### Non-Primitive Parameters + +When we compose components we often don't think about too much how we structure the data we pass along to the component. For example, it may seem easier to just define an interface to represent a menu rather than creating extra components for menu items. + +Let's say we define a custom component for the footer menu on [stenciljs.com](https://stenciljs.com/): + +```tsx +const menu = { + 'Overview': ['Introduction', 'Getting Started', 'Component API', 'Guides', 'FAQ'], + 'Docs': ['Framework Integrations', 'Static Site Generation', 'Config', 'Output Targets', 'Testing', 'Core Compiler API'], + 'Community': ['Blog', 'GitHub', 'X', 'Discord'] +} +return ( + +) +``` + +While this works just fine when rendering the component in the browser, it may be challenging when rendering it on the server. Stencil __does not support__ the serialization of objects within parameters, causing the component to not server side render any footer menu items. + +In situations where parameters \ No newline at end of file From 44f4a85946e4affcc7444b501a2e5ead85eb5cf2 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Tue, 22 Oct 2024 16:36:41 -0700 Subject: [PATCH 02/10] add more content --- docs/guides/server-side-rendering.md | 119 ++++++++++++++++++++++++++- 1 file changed, 118 insertions(+), 1 deletion(-) diff --git a/docs/guides/server-side-rendering.md b/docs/guides/server-side-rendering.md index 5891e5e03..193d58b3a 100644 --- a/docs/guides/server-side-rendering.md +++ b/docs/guides/server-side-rendering.md @@ -36,4 +36,121 @@ return ( While this works just fine when rendering the component in the browser, it may be challenging when rendering it on the server. Stencil __does not support__ the serialization of objects within parameters, causing the component to not server side render any footer menu items. -In situations where parameters \ No newline at end of file +In situations where you use parameters to render elements it is mostly better to structure them within the light DOM of the component instead of passing them along as parameters. Especially if parameters contribute to the structure of the component, it is usually a better approach to pass them in as DOM structure. + +For above example, a better solution would be: + +```tsx +const menu = { + 'Overview': ['Introduction', 'Getting Started', 'Component API', 'Guides', 'FAQ'], + 'Docs': ['Framework Integrations', 'Static Site Generation', 'Config', 'Output Targets', 'Testing', 'Core Compiler API'], + 'Community': ['Blog', 'GitHub', 'X', 'Discord'] +} +return ( + +) +``` + +With this approach your meta framework can properly generate a complete markup of your footer navigation without having to wait for your application runtime to hydrate the app. + +### Cross Component Context + +When components carry a certain state that you like to propagate to child components, there are several approaches that allows you to solve for that, e.g. reducers or context providers in React. If you use these state information to make decisions on how the element is being rendered you may run into issues when trying to server side render the application. + +In Next.js and other meta frameworks, every component is rendered individually from its parents and childrens. For example, given the following structure: + +```tsx + + + +``` + +When your application gets server side rendered, and e.g. Next.js wants to render `ParentComponent`, Stencil will try to parse the children into a string to give the `ParentComponent` information about its light DOM. The intermediate result of this operation will be as following: + +```tsx + + + + +``` + +In the process of rendering `ParentComponent` you have access to its light DOM, e.g. `ChildComponent`, which allows you to modify the component attributes. However, once `ParentComponent` and the framework moves forward to render `ChildComponent`, `ChildComponent` won't have access to `ParentComponent` as it is being rendered in an isolated environment. The same applies for any state objects you may import for the component, they may remain empty when the component is rendered. + +In summary, keep in mind that the part of your component that you want to server side render, should be able to do so without requiring any application state. If the component suppose to display data that is being loaded from the server during runtime, have the component render a loading view instead. + +### Performance + +To server side render a component, Stencil transforms your component into a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom). A Declarative Shadow DOM contains all structural information of your component including styles. Depending on how your components are set up, and how many components you render on the server this can have a huge impact on the document size. + +Imaging a small button component in Stencil: + +```tsx +import { Component, Fragment, h } from '@stencil/core' +@Component({ + tag: 'my-btn', + styleUrl: './button.css' +}) +export class MyBtn { + render() { + return ( + <> + + + ); + } +} +``` + +with `button.css` being something like: + +```css +/* button.css */ +@import "../css/base.css"; +@import "../css/tokens.css"; +@import "../css/animations.css"; +@import "../css/utilities.css"; + +/* component related styles: */ +button { + ... +} +``` + +It is convenient to just import all additional CSS the project uses even though it may not be used by the component itself. This can lead to performance issues in the context of server side rendering quickly. + +When Stencil transforms your component into a Declarative Shadow DOM, it includes all component styles into the template so that the component can be rendered imidiatelly. Now imagine you want to server side render a set of components: + +```tsx + +``` + +This will cause the document to contain all your CSS from above already 3 times and may increase your document size to a point where it impacts the [First Contentful Paint (FCP)](https://web.dev/articles/fcp) because the browser takes a long time to pull the whole document from the server. + +There are several ways to mitigate this: + +- Use CSS variables wherever possible as they have the capability to pierce through the Shadow DOM +- Use [`::part`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) CSS pseudo elements as they help styling sections of your Shadow DOM from the outside +- Optimize the CSS per component and don't include unused styles +- Limit the scope of what should be server side rendered, e.g. by applying `use client` in Next.js to these sections of the page that aren't on the critical rendering path + +Stencil will continue to improve the support for Server Side Rendering and will try to provide solutions for the challenges mentioned above. If you have ideas or feedback, don't hesitate to [file an issue](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=feature_request.yml&title=feat%3A+) and collaborate with us! \ No newline at end of file From aa775e5e9317e149afb16d5fc64eac127aff3927 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Tue, 22 Oct 2024 16:42:39 -0700 Subject: [PATCH 03/10] refine --- docs/guides/server-side-rendering.md | 76 +++++++++++----------------- 1 file changed, 29 insertions(+), 47 deletions(-) diff --git a/docs/guides/server-side-rendering.md b/docs/guides/server-side-rendering.md index 193d58b3a..11188aca8 100644 --- a/docs/guides/server-side-rendering.md +++ b/docs/guides/server-side-rendering.md @@ -5,21 +5,19 @@ description: Server Side Rendering slug: /server-side-rendering --- -# Server Side Rendering +# Server-Side Rendering (SSR) with Stencil -For React and Vue Output Targets Stencil has support for Server Side Rendering (SSR). If you use frameworks such as [Next.js](https://nextjs.org/) or [Nuxt](https://nuxt.com/) Stencil will automatically enhance the framework to allow render Stencil components on the server into a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom). +Stencil provides server-side rendering (SSR) support for React and Vue output targets. If you're using frameworks like [Next.js](https://nextjs.org/) or [Nuxt](https://nuxt.com/), Stencil automatically enhances these frameworks to render components on the server using a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom). -You can find more information on how to setup SSR support for [React](/docs/react) and [Vue](/docs/vue) in their respective Output Target documentations. All interfaces related to rendering a Stencil component into a string are exported by the [Stencil Hyrdate Module](/docs/hydrate-app). +For detailed setup instructions, refer to the SSR documentation for [React](/docs/react) and [Vue](/docs/vue). All interfaces needed for rendering Stencil components into a string are exported through the [Stencil Hydrate Module](/docs/hydrate-app). -## Tips & Tricks +## Tips & Best Practices -When server side rendering a component you may run into a few gotchas that may seem confusing when components don't appear as expected. Here are some important tips and tricks you should know to avoid these situations. +When server-side rendering Stencil components, there are a few potential pitfalls you might encounter. To help you avoid these issues, here are some key tips and best practices. -### Non-Primitive Parameters +### Avoid Non-Primitive Parameters -When we compose components we often don't think about too much how we structure the data we pass along to the component. For example, it may seem easier to just define an interface to represent a menu rather than creating extra components for menu items. - -Let's say we define a custom component for the footer menu on [stenciljs.com](https://stenciljs.com/): +When building components, it's common to pass complex data structures like objects to components as props. For example, a footer menu could be structured as an object rather than as separate components for each menu item: ```tsx const menu = { @@ -34,11 +32,9 @@ return ( ) ``` -While this works just fine when rendering the component in the browser, it may be challenging when rendering it on the server. Stencil __does not support__ the serialization of objects within parameters, causing the component to not server side render any footer menu items. - -In situations where you use parameters to render elements it is mostly better to structure them within the light DOM of the component instead of passing them along as parameters. Especially if parameters contribute to the structure of the component, it is usually a better approach to pass them in as DOM structure. +While this approach works fine in the browser, it poses challenges for SSR. Stencil **does not support** the serialization of complex objects within parameters, so the footer items may not render on the server. -For above example, a better solution would be: +A better approach is to structure dynamic content as part of the component's light DOM rather than passing it as props. This ensures that the framework can fully render the component during SSR, avoiding hydration issues. Here’s an improved version of the example: ```tsx const menu = { @@ -52,7 +48,7 @@ return ( {Object.entries(menu).map(([section, links]) => (

{section}

- {links.map((link) => ( + {links.map(link => ( {link} ))} @@ -62,13 +58,13 @@ return ( ) ``` -With this approach your meta framework can properly generate a complete markup of your footer navigation without having to wait for your application runtime to hydrate the app. +By rendering the menu directly in the light DOM, SSR can produce a complete, ready-to-render markup. -### Cross Component Context +### Cross-Component State Handling -When components carry a certain state that you like to propagate to child components, there are several approaches that allows you to solve for that, e.g. reducers or context providers in React. If you use these state information to make decisions on how the element is being rendered you may run into issues when trying to server side render the application. +When propagating state between parent and child components, patterns like reducers or context providers (as in React) are often used. However, this can be problematic with SSR in frameworks like Next.js, where each component is rendered independently. -In Next.js and other meta frameworks, every component is rendered individually from its parents and childrens. For example, given the following structure: +Consider the following structure: ```tsx @@ -76,7 +72,7 @@ In Next.js and other meta frameworks, every component is rendered individually f ``` -When your application gets server side rendered, and e.g. Next.js wants to render `ParentComponent`, Stencil will try to parse the children into a string to give the `ParentComponent` information about its light DOM. The intermediate result of this operation will be as following: +When `ParentComponent` is rendered on the server, Stencil will attempt to stringify its children (e.g., `ChildComponent`) for the light DOM. The intermediate markup may look like this: ```tsx @@ -88,15 +84,15 @@ When your application gets server side rendered, and e.g. Next.js wants to rende ``` -In the process of rendering `ParentComponent` you have access to its light DOM, e.g. `ChildComponent`, which allows you to modify the component attributes. However, once `ParentComponent` and the framework moves forward to render `ChildComponent`, `ChildComponent` won't have access to `ParentComponent` as it is being rendered in an isolated environment. The same applies for any state objects you may import for the component, they may remain empty when the component is rendered. +At this stage, `ParentComponent` can access and manipulate its children. However, when `ChildComponent` is rendered in isolation, it won’t have access to the parent’s state or context, potentially leading to inconsistencies. -In summary, keep in mind that the part of your component that you want to server side render, should be able to do so without requiring any application state. If the component suppose to display data that is being loaded from the server during runtime, have the component render a loading view instead. +To prevent this, ensure that components rendered on the server don’t depend on external state or context. If the component relies on data fetched at runtime, it’s better to display a loading placeholder during SSR. -### Performance +### Optimizing Performance -To server side render a component, Stencil transforms your component into a [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom). A Declarative Shadow DOM contains all structural information of your component including styles. Depending on how your components are set up, and how many components you render on the server this can have a huge impact on the document size. +When Stencil server-side renders a component, it converts it into [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom), which includes all structural information and styles. While this ensures accurate rendering, it can significantly increase document size if not managed carefully. -Imaging a small button component in Stencil: +For example, consider a button component: ```tsx import { Component, Fragment, h } from '@stencil/core' @@ -115,7 +111,7 @@ export class MyBtn { } ``` -with `button.css` being something like: +And this `button.css` which imports additional common styles: ```css /* button.css */ @@ -124,33 +120,19 @@ with `button.css` being something like: @import "../css/animations.css"; @import "../css/utilities.css"; -/* component related styles: */ +/* component-specific styles */ button { ... } ``` -It is convenient to just import all additional CSS the project uses even though it may not be used by the component itself. This can lead to performance issues in the context of server side rendering quickly. - -When Stencil transforms your component into a Declarative Shadow DOM, it includes all component styles into the template so that the component can be rendered imidiatelly. Now imagine you want to server side render a set of components: - -```tsx - -``` - -This will cause the document to contain all your CSS from above already 3 times and may increase your document size to a point where it impacts the [First Contentful Paint (FCP)](https://web.dev/articles/fcp) because the browser takes a long time to pull the whole document from the server. +When SSR is performed, the entire CSS (including imports) is bundled with the component’s declarative shadow DOM. Rendering multiple instances of this button in SSR can lead to repeated inclusion of styles, bloating the document size and delaying [First Contentful Paint (FCP)](https://web.dev/articles/fcp). -There are several ways to mitigate this: +Here are some ways to mitigate this: -- Use CSS variables wherever possible as they have the capability to pierce through the Shadow DOM -- Use [`::part`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) CSS pseudo elements as they help styling sections of your Shadow DOM from the outside -- Optimize the CSS per component and don't include unused styles -- Limit the scope of what should be server side rendered, e.g. by applying `use client` in Next.js to these sections of the page that aren't on the critical rendering path +- **Use CSS Variables**: CSS variables can pierce the Shadow DOM, reducing the need for redundant styles. +- **Use the `::part` pseudo-element**: This allows you to style parts of the Shadow DOM from outside the component, minimizing the internal CSS. +- **Optimize Component-Specific CSS**: Only include the necessary styles for each component. +- **Limit SSR Scope**: In Next.js, apply `use client` to sections that don’t need SSR to reduce unnecessary rendering. -Stencil will continue to improve the support for Server Side Rendering and will try to provide solutions for the challenges mentioned above. If you have ideas or feedback, don't hesitate to [file an issue](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=feature_request.yml&title=feat%3A+) and collaborate with us! \ No newline at end of file +Stencil continues to enhance SSR capabilities and is committed to solving performance and rendering challenges. Your feedback is important — feel free to [file an issue](https://github.com/ionic-team/stencil/issues/new?assignees=&labels=&projects=&template=feature_request.yml&title=feat%3A+) and contribute your ideas! From bf37a8f185084f9729c25bb7295958e7d9dcc0f0 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Tue, 22 Oct 2024 16:45:04 -0700 Subject: [PATCH 04/10] add Nuxt as word to cspell --- cspell-wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell-wordlist.txt b/cspell-wordlist.txt index 090262807..9770f70d9 100644 --- a/cspell-wordlist.txt +++ b/cspell-wordlist.txt @@ -20,6 +20,7 @@ expressjs lifecycles microtask minifier +Nuxt polyfilling precache prehydration From d1ffbd60d2b387020db78c606945c649508be9c1 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 23 Oct 2024 10:42:14 -0700 Subject: [PATCH 05/10] Update docs/framework-integration/react.md Co-authored-by: Tanner Reits <47483144+tanner-reits@users.noreply.github.com> --- docs/framework-integration/react.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework-integration/react.md b/docs/framework-integration/react.md index 4c809a68f..81d4841dd 100644 --- a/docs/framework-integration/react.md +++ b/docs/framework-integration/react.md @@ -387,7 +387,7 @@ If your React framework supports server side rendering, e.g. [Next.js](https://n ``` 2. Create an export for the compiled files within the `/hydrate` directory, e.g. - ```json + ```json title="package.json" { "name": "component-library", ... From fb932810da6afbd0cc3bc24da721c897660be514 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 23 Oct 2024 10:42:22 -0700 Subject: [PATCH 06/10] Update docs/framework-integration/react.md Co-authored-by: Tanner Reits <47483144+tanner-reits@users.noreply.github.com> --- docs/framework-integration/react.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework-integration/react.md b/docs/framework-integration/react.md index 81d4841dd..8686bd7c6 100644 --- a/docs/framework-integration/react.md +++ b/docs/framework-integration/react.md @@ -406,7 +406,7 @@ If your React framework supports server side rendering, e.g. [Next.js](https://n ``` 3. Set the `hydrateModule` in your React output target configuration, e.g. - ```ts + ```ts title="stencil.config.ts" import { Config } from '@stencil/core'; import { reactOutputTarget } from '@stencil/react-output-target'; From 94bb46d03bdd4771dccb079f11417061334fa72b Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 23 Oct 2024 10:42:42 -0700 Subject: [PATCH 07/10] Update docs/framework-integration/react.md Co-authored-by: Tanner Reits <47483144+tanner-reits@users.noreply.github.com> --- docs/framework-integration/react.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework-integration/react.md b/docs/framework-integration/react.md index 8686bd7c6..f285c7189 100644 --- a/docs/framework-integration/react.md +++ b/docs/framework-integration/react.md @@ -425,7 +425,7 @@ That's it! Your Next.js application should now render a Declarative Shadow DOM o :::cautions -A Declarative Shadow DOM contains next to the HTML structure also all the CSS defined for the component. If you server side render a lot of small components that come with large amounts of CSS, it will drastically increase the initial page load time as the documented loaded by the browser increases in size. Make sure to keep the initial document size reasonable and aligned with your performance goals, server side rendering only the critical components needed to render the viewport and load the rest later on. +A Declarative Shadow DOM contains next to the HTML structure also all the CSS defined for the component. If you server side render a lot of small components that come with large amounts of CSS, it will drastically increase the initial page load time as the document loaded by the browser increases in size. Make sure to keep the initial document size reasonable and aligned with your performance goals. It is recommended to server side rendering only the critical components needed to render the viewport and load the rest later on. ::: From eb2a661a0814616110351bbced3195cae5cf21f8 Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 23 Oct 2024 10:42:47 -0700 Subject: [PATCH 08/10] Update docs/framework-integration/vue.md Co-authored-by: Tanner Reits <47483144+tanner-reits@users.noreply.github.com> --- docs/framework-integration/vue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework-integration/vue.md b/docs/framework-integration/vue.md index 6a134b67e..311485051 100644 --- a/docs/framework-integration/vue.md +++ b/docs/framework-integration/vue.md @@ -368,7 +368,7 @@ If your Vue framework supports server side rendering, e.g. when using [Nuxt](htt ``` 2. Create an export for the compiled files within the `/hydrate` directory, e.g. - ```json + ```json title="package.json" { "name": "component-library", ... From 6f809036cf7cca0f7874f2824bd6eb31ba7427ce Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 23 Oct 2024 10:42:52 -0700 Subject: [PATCH 09/10] Update docs/framework-integration/vue.md Co-authored-by: Tanner Reits <47483144+tanner-reits@users.noreply.github.com> --- docs/framework-integration/vue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework-integration/vue.md b/docs/framework-integration/vue.md index 311485051..76ec3479b 100644 --- a/docs/framework-integration/vue.md +++ b/docs/framework-integration/vue.md @@ -387,7 +387,7 @@ If your Vue framework supports server side rendering, e.g. when using [Nuxt](htt ``` 3. Set the `hydrateModule` in your React output target configuration, e.g. - ```ts + ```ts title="stencil.config.ts" import { Config } from '@stencil/core'; import { vueOutputTarget } from '@stencil/vue-output-target'; From bc3caf2f3c4b33d0b35cb76edfe65a3f2bad434c Mon Sep 17 00:00:00 2001 From: Christian Bromann Date: Wed, 23 Oct 2024 10:46:20 -0700 Subject: [PATCH 10/10] minor tweaks --- docs/framework-integration/react.md | 2 +- docs/framework-integration/vue.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/framework-integration/react.md b/docs/framework-integration/react.md index f285c7189..6d087626a 100644 --- a/docs/framework-integration/react.md +++ b/docs/framework-integration/react.md @@ -425,7 +425,7 @@ That's it! Your Next.js application should now render a Declarative Shadow DOM o :::cautions -A Declarative Shadow DOM contains next to the HTML structure also all the CSS defined for the component. If you server side render a lot of small components that come with large amounts of CSS, it will drastically increase the initial page load time as the document loaded by the browser increases in size. Make sure to keep the initial document size reasonable and aligned with your performance goals. It is recommended to server side rendering only the critical components needed to render the viewport and load the rest later on. +A Declarative Shadow DOM not only encapsulates the HTML structure of a component but also includes all associated CSS. When server-side rendering numerous small components with extensive CSS, the overall document size can significantly increase, leading to longer initial page load times. To optimize performance, it's essential to maintain a manageable document size that aligns with your performance objectives. It is advisable to server-side render only the critical components required for rendering the initial viewport, while deferring the loading of additional components until after the initial render. ::: diff --git a/docs/framework-integration/vue.md b/docs/framework-integration/vue.md index 76ec3479b..86410de7c 100644 --- a/docs/framework-integration/vue.md +++ b/docs/framework-integration/vue.md @@ -410,7 +410,7 @@ That's it! Your Nuxt application should now render a Declarative Shadow DOM on t :::cautions -A Declarative Shadow DOM contains next to the HTML structure also all the CSS defined for the component. If you server side render a lot of small components that come with large amounts of CSS, it will drastically increase the initial page load time as the documented loaded by the browser increases in size. Make sure to keep the initial document size reasonable and aligned with your performance goals, server side rendering only the critical components needed to render the viewport and load the rest later on. +A Declarative Shadow DOM not only encapsulates the HTML structure of a component but also includes all associated CSS. When server-side rendering numerous small components with extensive CSS, the overall document size can significantly increase, leading to longer initial page load times. To optimize performance, it's essential to maintain a manageable document size that aligns with your performance objectives. It is advisable to server-side render only the critical components required for rendering the initial viewport, while deferring the loading of additional components until after the initial render. :::