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

| 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' |

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

| Approach | Advantages | Disadvantages | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 'wrapper' | Isolates components for modularity and CSS control. Maintains SEO benefits with pre-rendered content. Prevents layout shifts for a seamless experience. Simple integration compared to 'server-only'. Functionally remains after client-side hydration. Avoids CSS conflicts with global styles. | Content rendered on request (not pre-rendered). Custom server-side rendering implementation. Potential memory issues in constrained environments. | | 'server-only' | Leverages built-in Stencil rendering for speed. Pre-rendered content for SEO and fast display. | Potential XSS risk with dynamic content. Complex setup with React server components. Increases bundle size with redundant CSS. Limited user input (text only). Memory issues with large component counts. Client-side re-render with possible layout shift. Global CSS conflicts with component styles. | | Client-Side Rendering | Simple implementation with minimal code. Delivers fastest initial load times. | Triggers layout shifts during initial rendering. Content invisible to search engines (SEO impact). |

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.