@smartive/stencil-react-ssr-output-target v1.3.18

Stencil Output Targets for Next.js SSR

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.

Usage

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',
    });
  ],
};

Arguments and Defaults

Usage of generated Code

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: 1. Fully SSR supported React components with client rehydration (wrapper) 2. Prerendered SSR components with client rehydration (ssr-only) 3. Client components only (wrapper with use client).

1. 'wrapper' approach

1. Add await import('abc-web-components-react-wrapper/server'); to your root layout.tsx. Consider adding a polyfill for template-shadowroot. Consolidate caniuse to determine if the polyfill is necessary.
2. Create a new 'use client' component
3. 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>
);

1. Use your component in page.tsx

2. 'server-only' approach

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.

1. 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>
);

1. Use the ButtonSSR component in page.tsx

3. 'use client' approach

1. Create a new 'use client' component
2. 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>
);

1. 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.

Working Next.js Example

Live Demo: stencil-nextjs-example-app.vercel.app

Code: smartive/stencil-nextjs-example

Approaches

Key Considerations

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.

Server-Side Rendering with Wrapper ('wrapper' approach)

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.

Additional Information

• 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.

Generating Static HTML with Client-Side Hydration ('server-only' approach)

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.

Additional Information

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.

Comparison Table

Choosing the right approach

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.

Credits

• @luwes WeSC project served as a foundation.
• @muxinc Web Components React build script aided in creating the Stencil React Wrapper build script.