Using Web Components With Next (or Any SSR Framework)

My previous article explored Shoelace, a component library offering a comprehensive set of visually appealing, accessible UX components built using Web Components. This architecture allows framework-agnostic usage. While React's Web Component integration isn't optimal, workarounds exist.

A significant limitation of Web Components is their current lack of server-side rendering (SSR) support. Declarative Shadow DOM (DSD) is under development, but current support is limited and requires server-side modifications. Ongoing Next.js development in this area is promising. This article focuses on managing Web Components within any SSR framework, including Next.js, using current techniques.

This approach involves manual steps and a slight performance impact on initial page load. We'll address performance optimization strategies. This solution isn't without trade-offs; thorough testing and profiling are crucial.

The Challenge: SSR and Web Components

Why don't Web Components integrate seamlessly with SSR?

Frameworks like Next.js process React code, converting components into plain HTML. The React component tree renders on the server, and this HTML is sent to the client browser. Along with this HTML are tags loading React and component code. The browser re-renders the component tree, matching it with the server-rendered HTML. This process, known as hydration, activates effects, event handlers, and state management, making the application interactive.

Web Components complicate this. When rendering a component like Shoelace's <sl-tab-group></sl-tab-group>:

<sl-tab-group ref="{tabsRef}">
  <sl-tab panel="general" slot="nav">General</sl-tab>
  <sl-tab panel="custom" slot="nav">Custom</sl-tab>
  <sl-tab panel="advanced" slot="nav">Advanced</sl-tab>
  <sl-tab disabled panel="disabled" slot="nav">Disabled</sl-tab>
  <sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
  <sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
  <sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
  <sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>

React (or any JavaScript framework) passes these tags directly. The rendering logic resides within the Web Component's code (in this case, Shoelace). The timing of this code execution is critical.

Typically, Web Component registration occurs via a JavaScript import during hydration. This means the components won't render correctly until after hydration, leading to a flash of unstyled content (FOUC). While you could theoretically add placeholder markup, it's impractical, especially with third-party libraries.

Pre-Hydration Web Component Registration

The issue is the delayed execution of Web Component registration code until hydration. Our solution involves running this code earlier—immediately. We'll custom-bundle the Web Component code and add a blocking script to the document's . This is generally undesirable, as it contradicts the purpose of SSR, but it ensures immediate rendering. The performance impact will be mitigated by caching. This is not an ideal long-term solution. Future Next.js DSD support will likely eliminate this need.

Implementation Details

The complete code is available on this GitHub repository and deployed here using Vercel. The application renders Shoelace components alongside text that changes after hydration. The text will update to "Hydrated," while Shoelace components render correctly from the start.

Custom Bundling

First, create a JavaScript module importing all Web Component definitions. For Shoelace:

<sl-tab-group ref="{tabsRef}">
  <sl-tab panel="general" slot="nav">General</sl-tab>
  <sl-tab panel="custom" slot="nav">Custom</sl-tab>
  <sl-tab panel="advanced" slot="nav">Advanced</sl-tab>
  <sl-tab disabled panel="disabled" slot="nav">Disabled</sl-tab>
  <sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
  <sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
  <sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
  <sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>

This module cannot be imported directly; it must be custom-bundled to prevent inclusion in regular JavaScript bundles. I'll use Vite. Install it (npm i vite) and create vite.config.js:

import { setDefaultAnimation } from "@shoelace-style/shoelace/dist/utilities/animation-registry";

import "@shoelace-style/shoelace/dist/components/tab/tab.js";
import "@shoelace-style/shoelace/dist/components/tab-panel/tab-panel.js";
import "@shoelace-style/shoelace/dist/components/tab-group/tab-group.js";

import "@shoelace-style/shoelace/dist/components/dialog/dialog.js";

setDefaultAnimation("dialog.show", { /* ... */ });
setDefaultAnimation("dialog.hide", { /* ... */ });

This creates a bundle in shoelace-dir. Move it to the public folder for Next.js serving. A Node script manages this and creates a module exporting the bundle filename:

import { defineConfig } from "vite";
import path from "path";

export default defineConfig({
  build: {
    outDir: path.join(__dirname, "./shoelace-dir"),
    lib: {
      name: "shoelace",
      entry: "./src/shoelace-bundle.js",
      formats: ["umd"],
      fileName: () => "shoelace-bundle.js",
    },
    rollupOptions: {
      output: {
        entryFileNames: `[name]-[hash].js`,
      },
    },
  },
});

And a corresponding npm script:

// ... (Node script to move the bundle and create a module with the bundle path) ...

Script Loading

In Next.js's _document.js, import the bundle path and add a <script></script> tag to the :

"bundle-shoelace": "vite build && node util/process-shoelace-bundle",

This ensures the Web Component registration runs before the initial HTML rendering.

Performance Optimization: Caching

Add caching headers to the Next.js config to improve subsequent page loads:

// ... (_document.js with script tag added) ...

This leverages browser caching effectively.

Conclusion

While this method requires manual steps, it provides a workaround for the current limitations of Web Components and SSR. The benefits of framework-agnostic components and easier experimentation with new frameworks outweigh the initial implementation complexity. Future improvements in Web Component SSR support will likely simplify this process.

The above is the detailed content of Using Web Components With Next (or Any SSR Framework). For more information, please follow other related articles on the PHP Chinese website!