Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ssr: add docs for new SSR support #1510

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

ssr: add docs for new SSR support #1510

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7fc2034
ssr: add docs for new SSR support
christian-bromann Mar 8, 2025
eb8e824
minor tweaks
christian-bromann Mar 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 0 additions & 64 deletions docs/framework-integration/react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
67 changes: 0 additions & 67 deletions docs/framework-integration/vue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading