ssr: add docs for new SSR support (#1510)

* ssr: add docs for new SSR support

* minor tweaks

* add comment to assign properties dynamically

Author: christian-bromann

docs/framework-integration/react.md

@@ -393,70 +393,6 @@ 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 title="package.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 title="stencil.config.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.
-
-#### SSR Limitations
-
-Please be aware of the following limitations when working with server side rendered applications:
-
-- 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.
-- A Stencil component that dynamically renders content based on elements within its Light DOM may not render correctly as the Output Target can't always serialize the children of the React component into a template string especially when working with multiple nested Stencil components.
-- Currently Stencil does not support the serialization of objects within properties. This means that Stencil ignores server side rendering all properties that are defined with a reference types, e.g. `object`.
-
 ## API
 
 ### esModule

docs/framework-integration/vue.md

@@ -348,73 +348,6 @@ In your page or component, you can now import and use your component wrappers:
 </template>
 ```
 
-### 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 title="package.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 Vue output target configuration, e.g.
-    ```ts title="stencil.config.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.
-
-#### SSR Limitations
-
-Please be aware of the following limitations when working with server side rendered applications:
-
-- 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.
-- Currently Stencil does not support the serialization of objects within properties. This means that Stencil ignores server side rendering all properties that are defined with a reference types, e.g. `object`.
-
 ## API
 
 ### componentCorePackage

docs/guides/hydrate-app.md

@@ -190,7 +190,15 @@ If set to `true` it removes any abundant HTML comments. Stencil still requires t
 
 __Type:__ `(document: Document, url: URL) => <void> | Promise<void>`
 
-Allows to modify the document and all its containing components to be modified before the hydration process starts.
+Allows to modify the document and all its containing components to be modified before the hydration process starts. This allows e.g. to assign properties to the components dynamically:
+
+```ts
+await renderToString(response.body, {
+    beforeHydrate: (doc: Document) => {
+      doc.querySelector(`my-component`).someComplexThing = new Map(...)
+   },
+})
+```
 
 ##### `afterHydrate`