Web Components built with libraries like Shoelace are attractive precisely because they aren't bound to any framework — they can drop into React, Svelte, Solid or anything else. The friction starts at the server. There is no real support for server-side rendering (SSR) of custom elements today; Declarative Shadow DOM (DSD) exists as a proposal, but browser support is minimal and the server has to emit special markup for it. Next.js work in this area is underway, but until it lands, the workaround below applies to any SSR framework.

Where SSR and Web Components collide

Frameworks such as Next.js take the React component tree and stringify it on the server, shipping plain HTML to the browser alongside <script> tags. When those scripts execute, React re-renders the tree, matches it against the server output, attaches effects and event handlers, and restores state. That re-processing step is hydration, and it's the point at which the app becomes interactive.

Given markup like the Shoelace component below, React — or any framework — simply passes the tags through. Turning them into formatted tabs is the job of the code that defines the custom elements, and the question is when that code executes.

<sl-tab-group ref="{tabsRef}">
  <sl-tab slot="nav" panel="general"> General </sl-tab>
  <sl-tab slot="nav" panel="custom"> Custom </sl-tab>
  <sl-tab slot="nav" panel="advanced"> Advanced </sl-tab>
  <sl-tab slot="nav" panel="disabled" disabled> 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>

Normally the registration code arrives through a JavaScript import, gets bundled into the application, and runs during hydration. Until then, the browser displays the server HTML with nothing inside the custom element tags, so the surrounding content shifts once the real output appears. That flash of unstyled content (FOUC) can't be papered over by hand-filling markup between every <sl-tab-xyz> tag — not with a third-party library.

The fix is to move registration earlier: bundle it separately and load it as a blocking script in the document <head>. As a general practice, blocking scripts are a bad idea, and the first visit will always wait on the file. The registration code is small, and cache headers make later visits cheap, so the cost is small — but it is real, and may be unacceptable for some applications (commerce, for instance). Measure before committing.

Creating the bundle

A single module imports every custom element definition required. For the components in use here, it loads <sl-tab-group> and <sl-dialog> and overrides some default dialog animations.

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", {
  keyframes: [
    { opacity: 0, transform: "translate3d(0px, -20px, 0px)" },
    { opacity: 1, transform: "translate3d(0px, 0px, 0px)" },
  ],
  options: { duration: 250, easing: "cubic-bezier(0.785, 0.135, 0.150, 0.860)" },
});
setDefaultAnimation("dialog.hide", {
  keyframes: [
    { opacity: 1, transform: "translate3d(0px, 0px, 0px)" },
    { opacity: 0, transform: "translate3d(0px, 20px, 0px)" },
  ],
  options: { duration: 250, easing: "cubic-bezier(0.785, 0.135, 0.150, 0.860)" },
});

This module must not be imported normally, or it lands in the main bundle and runs at hydration — the exact FOUC being avoided. Next.js exposes webpack hooks for custom bundling, but Vite is simpler. Install it with npm i vite and add a vite.config.js:

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

The build writes a hashed file into shoelace-dir; it needs to move to public so Next.js serves it, and its exact filename must be recorded. A Node script handles both, emitting a module that exports the bundle name as a constant:

const fs = require("fs");
const path = require("path");

const shoelaceOutputPath = path.join(process.cwd(), "shoelace-dir");
const publicShoelacePath = path.join(process.cwd(), "public", "shoelace");

const files = fs.readdirSync(shoelaceOutputPath);

const shoelaceBundleFile = files.find(name => /^shoelace-bundle/.test(name));

fs.rmSync(publicShoelacePath, { force: true, recursive: true });

fs.mkdirSync(publicShoelacePath, { recursive: true });
fs.renameSync(path.join(shoelaceOutputPath, shoelaceBundleFile), path.join(publicShoelacePath, shoelaceBundleFile));
fs.rmSync(shoelaceOutputPath, { force: true, recursive: true });

fs.writeFileSync(path.join(process.cwd(), "util", "shoelace-bundle-info.js"), `export const shoelacePath = "/shoelace/${shoelaceBundleFile}";`);

Wired up through a companion npm script:

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

The generated util/shoelace-bundle-info.js then contains something like:

export const shoelacePath = "/shoelace/shoelace-bundle-a6f19317.js";

Injecting the head script

In \_document.js, import the bundle name constant:

import { shoelacePath } from "../util/shoelace-bundle-info";

and render a <script> tag for it by hand inside <head>:

import { Html, Head, Main, NextScript } from "next/document";
import { shoelacePath } from "../util/shoelace-bundle-info";

export default function Document() {
  return (
    <Html>
      <Head>
        <script src={shoelacePath}></script>
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

The Shoelace registration now runs as a blocking script, so the definitions exist the moment the initial HTML is processed and components render correct content immediately.

Making repeat visits cheap

Tell Next.js to cache the bundle with this entry in the config file:

async headers() {
  return [
    {
      source: "/shoelace/shoelace-bundle-:hash.js",
      headers: [
        {
          key: "Cache-Control",
          value: "public,max-age=31536000,immutable",
        },
      ],
    },
  ];
}

Subsequent browses hit the cache. Because the filename contains the :hash portion of the source property, any change to the bundle changes the name, the cache misses, and the browser fetches the new file.

DevTools Sources panel open and showing the loaded Shoelace bundle.

Weighing the tradeoff

The manual setup is substantial, and better out-of-the-box SSR support for Web Components would be welcome. The payoff is framework-independent UI: quality components for tabs, modals and autocompletes, reusable when experimenting with new frameworks such as Solid without rewriting or hacking them together. The reference implementation is at github.com/arackaf/next-wc-ssr, deployed on Vercel, with text that switches to "Hydrated" alongside correctly rendered Shoelace components.