This package exports reactSSROutputTarget
, which is a Stencil Output Target plugin. It wraps Stencil components within React components that can be used within the Next.js App Router. This allows you to improve the initial page load performance and SEO of your Next.js app.
import { Config } from '@stencil/core';
import { reactSSROutputTarget } from '@smartive/stencil-react-ssr-output-target';
export const config: Config = {
namespace: 'my-awesome-web-components',
outputTargets: [
reactSSROutputTarget({
package: {
name: 'my-awesome-react-wrapped-components',
version: '1.2.3',
},
outPath: 'build/ssr',
type: 'wrapper',
});
],
};
Property | Type | Description | Default |
---|---|---|---|
outPath |
string |
Path to the output directory for generated files. | 'dist/react-components-ssr' |
type |
'server-only' or 'wrapper'
|
Type of output to generate.'server-only' generates React Server Components for use with Next.js app folder.'wrapper' generates components which can be used in client components and are server side rendered with linkedom.More Information see Approaches and Usage of generated Code |
'server-only' |
package |
PackageJsonConfig |
Configuration for the generated package.json file. |
see next rows |
└ name
|
string |
Name of the package. | 'stencil-react-ssr' |
└ version
|
string |
Version of the package. | '0.0.0' |
└ author
|
string |
Author of the package. | 'Stencil React SSR' |
└ license
|
string |
License of the package. | 'ISC' |
This package is experimental and not yet tested with all use cases. Use generated code with caution.
You can use the generated components in three ways:
- Fully SSR supported React components with client rehydration (
wrapper
) - Prerendered SSR components with client rehydration (
ssr-only
) - Client components only (
wrapper
withuse client
).
- Add
await import('abc-web-components-react-wrapper/server');
to your rootlayout.tsx
. Consider adding a polyfill for template-shadowroot. Consolidate caniuse to determine if the polyfill is necessary. - Create a new
'use client'
component - Use the generated Wrapper to wrap your generated React Web Component:
'use client';
import { AbcWrapper } from 'abc-web-components-react-wrapper/client';
import { AbcButton } from 'abc-web-components-react-wrapper';
import { FC, PropsWithChildren } from 'react';
export const ButtonWithWrapper: FC<PropsWithChildren> = ({ children }) => (
<AbcWrapper>
<AbcButton variant="primary" size="md" as="button" onClick={(event) => console.info(event)}>
{children}
</AbcButton>
</AbcWrapper>
);
- Use your component in
page.tsx
This approach is a little more complicated since it uses the React Server Component approach which allows to run async code server side but not client side. Furthermore it relies on the possability to pass client components into server components as children and vice versa.
- Create two components one is for SSR usage and the other is the one rendered on the client: SSR:
import { AbcButtonServerOnly } from 'abc-web-components-react-wrapper';
import { FC, PropsWithChildren } from 'react';
import { ButtonWithSSR } from './button-with-ssr';
export const ButtonSSR: FC<PropsWithChildren> = ({ children }) => (
<ButtonWithSSR fallback={<AbcButtonServerOnly>{children}</AbcButtonServerOnly>}>{children}</ButtonWithSSR>
);
Client:
'use client';
import { AbcButton, WithSSR } from 'abc-web-components-react-wrapper';
import { ComponentProps, FC, PropsWithChildren } from 'react';
type Props = PropsWithChildren<ComponentProps<typeof WithSSR>>;
export const ButtonWithSSR: FC<Props> = ({ fallback, children }) => (
<WithSSR fallback={fallback}>
<AbcButton variant="primary" size="md" as="button" onClick={(event) => console.info(event)}>
{children}
</AbcButton>
</WithSSR>
);
- Use the
ButtonSSR
component inpage.tsx
- Create a new
'use client'
component - Use generated React Web Component:
'use client';
import { AbcButton } from 'abc-web-components-react-wrapper';
import { FC, PropsWithChildren } from 'react';
export const ButtonWithWrapper: FC<PropsWithChildren> = ({ children }) => (
<AbcButton variant="primary" size="md" as="button" onClick={(event) => console.info(event)}>
{children}
</AbcButton>
);
- Use your component in
page.tsx
[!NOTE] The
'use client'
approach is the simplest to implement but has the worst initial load times and SEO impact.
Live Demo: stencil-nextjs-example-app.vercel.app
Code: smartive/stencil-nextjs-example
Customization: This project is tailored to our client's specific use case, so modifications might be necessary for broader applicability. We welcome collaboration and contributions to enhance its accessibility.
Cautiousness: Both of the following approaches have potential security concerns. Exercise caution, especially when using user-generated content.
This approach utilizes linkedom, a library that emulates browser-like functionality on the server-side, to render Stencil components directly. This allows for faster initial page loads and improved SEO compared to client-side rendering.
- Uses a custom Stencil fork to enable
globalThis
fallback in server-side environments. - A related pull request and issue for official support were closed by the Stencil team.
This approach uses Stencil's "Hydrate App" feature to generate fully pre-rendered HTML and CSS files on the server, leading to faster initial page loads and improved SEO. The server sends this static content to the client, which subsequently replaces the static HTML with interactive versions of the Stencil components.
However, be aware of a potential security risk: This approach introduces potential Cross-Site Scripting (XSS) vulnerabilities because the server renders the HTML before knowing what data will be displayed. To mitigate this risk, never render user-generated content directly inside Web Components generated using this method.
This approach offers fast initial load times but requires client-side JavaScript execution for full interactivity. Consider alternative approaches like "wrapper" or "use client" if your application heavily relies on user-generated content or requires immediate interactivity. Always prioritize security and sanitize any user input before using it within Web Components.
Approach | Advantages | Disadvantages |
---|---|---|
'wrapper' |
|
|
'server-only' |
|
|
Client-Side Rendering |
|
|
The best approach depends on your project's specific needs and priorities. Consider factors like:
- SEO: If search engine visibility is crucial, server-only or wrapper might be better choices.
- Performance: Use client offers the fastest initial load times, while server-only and wrapper prioritize smooth rendering.
- Complexity: Server-only is the most complex, while use client is the simplest to implement.
- Memory usage: Consider memory constraints when choosing an approach.
- Functionality: If dynamic content with user input is needed, server-only might not be suitable. Remember, carefully evaluate your project's requirements before making a decision.
- @luwes WeSC project served as a foundation.
- @muxinc Web Components React build script aided in creating the Stencil React Wrapper build script.