docs(react): document new react output target flag for Next.js server…

… side rendering (#1458)

* docs(react): document new react output target flag for Next.js server side rendering

* more docs

* note Stencil only supports Next.js apps using App Router

* PR feedback

* docs(react): propagate to remaining versions

---------

Co-authored-by: Tanner Reits <[email protected]>

docs/framework-integration/react.md

@@ -17,6 +17,8 @@ This package includes an output target for code generation that allows developer
 - 🌐 Generate React functional component wrappers with JSX bindings for custom events and properties
 - ⌨️ Typings and auto-completion for React components in your IDE
 
+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.
+
 ## Setup
 
 ### Project Structure
@@ -212,7 +214,11 @@ file path to match your project's structure and respective names.
 
 See the [API section below](#api) for details on each of the output target's options.
 
-You can now build your Stencil component library to generate the component wrappers in your React component library.
+:::note
+In order to compile Stencil components optimized for server side rendering in e.g. Next.js applications that use [AppRouter](https://nextjs.org/docs/app), make sure to provide the [`hydrateModule`](#hydratemodule) property to the output target configuration.
+:::
+
+You can now build your Stencil component library to generate the component wrappers.
 
 ```bash npm2yarn
 # Build the library and wrappers
@@ -401,6 +407,41 @@ The directory where the React components will be generated. Accepts a relative p
 
 The name of the package that exports the Stencil components. Defaults to the package.json detected by the Stencil compiler.
 
+### hydrateModule
+
+**Optional**
+
+**Type: `string`**
+
+Enable React server side rendering (short SSR) for e.g. [Next.js](https://nextjs.org/) applications by providing an import path to the [hydrate module](../guides/hydrate-app.md) of your Stencil project that is generated through the `dist-hydrate-script` output target, e.g.:
+
+```ts title="stencil.config.ts"
+import type { Config } from '@stencil/core';
+
+/**
+ * excerpt from the Stencil example project:
+ * https://github.com/ionic-team/stencil-ds-output-targets/tree/cb/nextjs/packages/example-project
+ */
+export const config: Config = {
+  namespace: 'component-library',
+  outputTargets: [
+    reactOutputTarget({
+      outDir: '../next-app/src/app',
+      hydrateModule: 'component-library/hydrate'
+    }),
+    {
+      type: 'dist-hydrate-script',
+      dir: './hydrate',
+    },
+    // ...
+  ],
+};
+```
+
+:::note
+Next.js support is only available for applications that use the [Next.js App Router](https://nextjs.org/docs/app).
+:::
+
 ## FAQ's
 
 ### What is the best format to write event names?

versioned_docs/version-v4.0/framework-integration/react.md

@@ -15,6 +15,8 @@ a React application. The benefits of using Stencil's component wrappers over the
 - Custom events will be handled correctly and correctly propagate through the React render tree
 - Properties and attributes that are not a string or number will be correctly bound to the component
 
+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.
+
 ## Setup
 
 ### Project Structure
@@ -211,6 +213,10 @@ The `componentCorePackage` should match the `name` field in your Stencil project
 
 See the [API section below](#api) for details on each of the output target's options.
 
+:::note
+In order to compile Stencil components optimized for server side rendering in e.g. Next.js applications that use [AppRouter](https://nextjs.org/docs/app), make sure to provide the [`hydrateModule`](#hydratemodule) property to the output target configuration.
+:::
+
 You can now build your Stencil component library to generate the component wrappers.
 
 ```bash npm2yarn
@@ -460,6 +466,41 @@ The path to where the `defineCustomElements` helper method exists within the bui
 
 This parameter allows you to name the file that contains all the component wrapper definitions produced during the compilation process. This is the first file you should import in your React project.
 
+### hydrateModule
+
+**Optional**
+
+**Type: `string`**
+
+Enable React server side rendering (short SSR) for e.g. [Next.js](https://nextjs.org/) applications by providing an import path to the [hydrate module](../guides/hydrate-app.md) of your Stencil project that is generated through the `dist-hydrate-script` output target, e.g.:
+
+```ts title="stencil.config.ts"
+import type { Config } from '@stencil/core';
+
+/**
+ * excerpt from the Stencil example project:
+ * https://github.com/ionic-team/stencil-ds-output-targets/tree/cb/nextjs/packages/example-project
+ */
+export const config: Config = {
+  namespace: 'component-library',
+  outputTargets: [
+    reactOutputTarget({
+      outDir: '../next-app/src/app',
+      hydrateModule: 'component-library/hydrate'
+    }),
+    {
+      type: 'dist-hydrate-script',
+      dir: './hydrate',
+    },
+    // ...
+  ],
+};
+```
+
+:::note
+Next.js support is only available for applications that use the [Next.js App Router](https://nextjs.org/docs/app).
+:::
+
 ## FAQ's
 
 ### Do I have to use the `dist` output target?

versioned_docs/version-v4.1/framework-integration/react.md

@@ -15,6 +15,8 @@ a React application. The benefits of using Stencil's component wrappers over the
 - Custom events will be handled correctly and correctly propagate through the React render tree
 - Properties and attributes that are not a string or number will be correctly bound to the component
 
+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.
+
 ## Setup
 
 ### Project Structure
@@ -211,6 +213,10 @@ The `componentCorePackage` should match the `name` field in your Stencil project
 
 See the [API section below](#api) for details on each of the output target's options.
 
+:::note
+In order to compile Stencil components optimized for server side rendering in e.g. Next.js applications that use [AppRouter](https://nextjs.org/docs/app), make sure to provide the [`hydrateModule`](#hydratemodule) property to the output target configuration.
+:::
+
 You can now build your Stencil component library to generate the component wrappers.
 
 ```bash npm2yarn
@@ -460,6 +466,41 @@ The path to where the `defineCustomElements` helper method exists within the bui
 
 This parameter allows you to name the file that contains all the component wrapper definitions produced during the compilation process. This is the first file you should import in your React project.
 
+### hydrateModule
+
+**Optional**
+
+**Type: `string`**
+
+Enable React server side rendering (short SSR) for e.g. [Next.js](https://nextjs.org/) applications by providing an import path to the [hydrate module](../guides/hydrate-app.md) of your Stencil project that is generated through the `dist-hydrate-script` output target, e.g.:
+
+```ts title="stencil.config.ts"
+import type { Config } from '@stencil/core';
+
+/**
+ * excerpt from the Stencil example project:
+ * https://github.com/ionic-team/stencil-ds-output-targets/tree/cb/nextjs/packages/example-project
+ */
+export const config: Config = {
+  namespace: 'component-library',
+  outputTargets: [
+    reactOutputTarget({
+      outDir: '../next-app/src/app',
+      hydrateModule: 'component-library/hydrate'
+    }),
+    {
+      type: 'dist-hydrate-script',
+      dir: './hydrate',
+    },
+    // ...
+  ],
+};
+```
+
+:::note
+Next.js support is only available for applications that use the [Next.js App Router](https://nextjs.org/docs/app).
+:::
+
 ## FAQ's
 
 ### Do I have to use the `dist` output target?

versioned_docs/version-v4.10/framework-integration/react.md

@@ -15,6 +15,8 @@ a React application. The benefits of using Stencil's component wrappers over the
 - Custom events will be handled correctly and correctly propagate through the React render tree
 - Properties and attributes that are not a string or number will be correctly bound to the component
 
+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.
+
 ## Setup
 
 ### Project Structure
@@ -211,6 +213,10 @@ The `componentCorePackage` should match the `name` field in your Stencil project
 
 See the [API section below](#api) for details on each of the output target's options.
 
+:::note
+In order to compile Stencil components optimized for server side rendering in e.g. Next.js applications that use [AppRouter](https://nextjs.org/docs/app), make sure to provide the [`hydrateModule`](#hydratemodule) property to the output target configuration.
+:::
+
 You can now build your Stencil component library to generate the component wrappers.
 
 ```bash npm2yarn
@@ -460,6 +466,41 @@ The path to where the `defineCustomElements` helper method exists within the bui
 
 This parameter allows you to name the file that contains all the component wrapper definitions produced during the compilation process. This is the first file you should import in your React project.
 
+### hydrateModule
+
+**Optional**
+
+**Type: `string`**
+
+Enable React server side rendering (short SSR) for e.g. [Next.js](https://nextjs.org/) applications by providing an import path to the [hydrate module](../guides/hydrate-app.md) of your Stencil project that is generated through the `dist-hydrate-script` output target, e.g.:
+
+```ts title="stencil.config.ts"
+import type { Config } from '@stencil/core';
+
+/**
+ * excerpt from the Stencil example project:
+ * https://github.com/ionic-team/stencil-ds-output-targets/tree/cb/nextjs/packages/example-project
+ */
+export const config: Config = {
+  namespace: 'component-library',
+  outputTargets: [
+    reactOutputTarget({
+      outDir: '../next-app/src/app',
+      hydrateModule: 'component-library/hydrate'
+    }),
+    {
+      type: 'dist-hydrate-script',
+      dir: './hydrate',
+    },
+    // ...
+  ],
+};
+```
+
+:::note
+Next.js support is only available for applications that use the [Next.js App Router](https://nextjs.org/docs/app).
+:::
+
 ## FAQ's
 
 ### Do I have to use the `dist` output target?

versioned_docs/version-v4.11/framework-integration/react.md

@@ -15,6 +15,8 @@ a React application. The benefits of using Stencil's component wrappers over the
 - Custom events will be handled correctly and correctly propagate through the React render tree
 - Properties and attributes that are not a string or number will be correctly bound to the component
 
+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.
+
 ## Setup
 
 ### Project Structure
@@ -211,6 +213,10 @@ The `componentCorePackage` should match the `name` field in your Stencil project
 
 See the [API section below](#api) for details on each of the output target's options.
 
+:::note
+In order to compile Stencil components optimized for server side rendering in e.g. Next.js applications that use [AppRouter](https://nextjs.org/docs/app), make sure to provide the [`hydrateModule`](#hydratemodule) property to the output target configuration.
+:::
+
 You can now build your Stencil component library to generate the component wrappers.
 
 ```bash npm2yarn
@@ -460,6 +466,41 @@ The path to where the `defineCustomElements` helper method exists within the bui
 
 This parameter allows you to name the file that contains all the component wrapper definitions produced during the compilation process. This is the first file you should import in your React project.
 
+### hydrateModule
+
+**Optional**
+
+**Type: `string`**
+
+Enable React server side rendering (short SSR) for e.g. [Next.js](https://nextjs.org/) applications by providing an import path to the [hydrate module](../guides/hydrate-app.md) of your Stencil project that is generated through the `dist-hydrate-script` output target, e.g.:
+
+```ts title="stencil.config.ts"
+import type { Config } from '@stencil/core';
+
+/**
+ * excerpt from the Stencil example project:
+ * https://github.com/ionic-team/stencil-ds-output-targets/tree/cb/nextjs/packages/example-project
+ */
+export const config: Config = {
+  namespace: 'component-library',
+  outputTargets: [
+    reactOutputTarget({
+      outDir: '../next-app/src/app',
+      hydrateModule: 'component-library/hydrate'
+    }),
+    {
+      type: 'dist-hydrate-script',
+      dir: './hydrate',
+    },
+    // ...
+  ],
+};
+```
+
+:::note
+Next.js support is only available for applications that use the [Next.js App Router](https://nextjs.org/docs/app).
+:::
+
 ## FAQ's
 
 ### Do I have to use the `dist` output target?

versioned_docs/version-v4.12/framework-integration/react.md

@@ -15,6 +15,8 @@ a React application. The benefits of using Stencil's component wrappers over the
 - Custom events will be handled correctly and correctly propagate through the React render tree
 - Properties and attributes that are not a string or number will be correctly bound to the component
 
+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.
+
 ## Setup
 
 ### Project Structure
@@ -211,6 +213,10 @@ The `componentCorePackage` should match the `name` field in your Stencil project
 
 See the [API section below](#api) for details on each of the output target's options.
 
+:::note
+In order to compile Stencil components optimized for server side rendering in e.g. Next.js applications that use [AppRouter](https://nextjs.org/docs/app), make sure to provide the [`hydrateModule`](#hydratemodule) property to the output target configuration.
+:::
+
 You can now build your Stencil component library to generate the component wrappers.
 
 ```bash npm2yarn
@@ -460,6 +466,41 @@ The path to where the `defineCustomElements` helper method exists within the bui
 
 This parameter allows you to name the file that contains all the component wrapper definitions produced during the compilation process. This is the first file you should import in your React project.
 
+### hydrateModule
+
+**Optional**
+
+**Type: `string`**
+
+Enable React server side rendering (short SSR) for e.g. [Next.js](https://nextjs.org/) applications by providing an import path to the [hydrate module](../guides/hydrate-app.md) of your Stencil project that is generated through the `dist-hydrate-script` output target, e.g.:
+
+```ts title="stencil.config.ts"
+import type { Config } from '@stencil/core';
+
+/**
+ * excerpt from the Stencil example project:
+ * https://github.com/ionic-team/stencil-ds-output-targets/tree/cb/nextjs/packages/example-project
+ */
+export const config: Config = {
+  namespace: 'component-library',
+  outputTargets: [
+    reactOutputTarget({
+      outDir: '../next-app/src/app',
+      hydrateModule: 'component-library/hydrate'
+    }),
+    {
+      type: 'dist-hydrate-script',
+      dir: './hydrate',
+    },
+    // ...
+  ],
+};
+```
+
+:::note
+Next.js support is only available for applications that use the [Next.js App Router](https://nextjs.org/docs/app).
+:::
+
 ## FAQ's
 
 ### Do I have to use the `dist` output target?