Server Side Rendering

What Is SSR for Web Components?

Server-side rendering means generating HTML on the server before sending it to the browser. For Web Components, SSR helps improve first paint, SEO, and perceived performance, but custom elements still need client-side JavaScript to upgrade and become fully interactive.

Modern SSR for Web Components often relies on declarative Shadow DOM, fallback light DOM content, and hydration patterns that connect server HTML to client behavior.

Basic Declarative Shadow DOM SSR Example

<profile-card>
  <template shadowrootmode="open">
    <style>
      :host { display: block; }
      .card {
        padding: 1rem;
        border: 1px solid #dbe5f1;
        border-radius: 0.75rem;
      }
    </style>
    <article class="card">
      <slot></slot>
    </article>
  </template>
  <h2>Alex Chen</h2>
  <p>Frontend Developer</p>
</profile-card>

The browser can render encapsulated markup on first paint without waiting for JavaScript to call attachShadow(). Client code can still register the custom element later for interactivity.

SSR Challenges for Web Components

Client Upgrade After SSR

class ProfileCard extends HTMLElement {
  connectedCallback() {
    if (!this.shadowRoot) {
      this.attachShadow({ mode: "open" });
      this.shadowRoot.innerHTML = `
        <style>
          .card { padding: 1rem; }
        </style>
        <article class="card">
          <slot></slot>
        </article>
      `;
    }

    this.classList.add("ready");
  }
}

customElements.define("profile-card", ProfileCard);

On the client, check whether a declarative shadow root already exists before calling attachShadow(). This avoids errors and supports progressive enhancement.

Progressive Enhancement Pattern

<alert-banner type="success">
  Profile saved successfully.
</alert-banner>

<noscript>
  <div class="alert alert-success" role="alert">
    Profile saved successfully.
  </div>
</noscript>

Even with SSR, some users may have JavaScript disabled or delayed. Provide meaningful HTML content inside custom elements and consider fallback markup for critical UI.

SSR with Astro

---
// profile-card.astro
const name = "Alex Chen";
const role = "Frontend Developer";
---

<profile-card>
  <template shadowrootmode="open">
    <style>
      :host { display: block; }
    </style>
    <article><slot></slot></article>
  </template>
  <h2>{name}</h2>
  <p>{role}</p>
</profile-card>

<script>
  import "./profile-card.js";
</script>

Astro is well suited for SSR because it renders HTML on the server by default. Combine server HTML with a client script that registers and hydrates the custom element.

Hydration and Event Binding

class AppButton extends HTMLElement {
  connectedCallback() {
    if (this._hydrated) return;
    this._hydrated = true;

    const button =
      this.shadowRoot?.querySelector("button") ||
      this.querySelector("button");

    button?.addEventListener("click", () => {
      this.dispatchEvent(
        new CustomEvent("app-click", {
          bubbles: true,
          composed: true
        })
      );
    });
  }
}

Hydration means attaching listeners and stateful behavior to HTML that already exists. Guard against double initialization when the component connects more than once.

SEO and Accessibility with SSR

• Render meaningful text content inside custom elements on the server.
• Use semantic HTML in slotted content such as headings and paragraphs.
• Include accessible roles and labels in server HTML when possible.
• Avoid empty custom element shells with no visible content.
• Ensure critical content does not depend only on client rendering.
• Test pages with JavaScript disabled for essential content visibility.

SSR vs Client-Only Rendering

Passing Data from Server to Component

<user-badge
  name="Alex Chen"
  role="admin"
></user-badge>

class UserBadge extends HTMLElement {
  static get observedAttributes() {
    return ["name", "role"];
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  render() {
    const name = this.getAttribute("name") || "Guest";
    const role = this.getAttribute("role") || "viewer";

    if (!this.shadowRoot) {
      this.attachShadow({ mode: "open" });
    }

    this.shadowRoot.innerHTML = `
      <span class="badge">${name} (${role})</span>
    `;
  }
}

Attributes are a reliable SSR-friendly way to pass simple data from server HTML to custom elements. Use properties after hydration for richer client-side values.

When to Use SSR with Web Components

• You need fast first paint for public marketing or docs pages.
• SEO matters for content rendered inside custom elements.
• You ship design system demos or documentation sites.
• You want progressive enhancement before JS loads.
• You use frameworks like Astro that render HTML on the server.
• Accessibility requires visible content on initial render.

Common SSR Use Cases

• Component library documentation sites.
• Marketing pages using shared custom elements.
• Blogs and content sites with encapsulated UI widgets.
• E-commerce product cards and badges.
• Public dashboards with initial server-rendered state.
• Framework-agnostic UI packages distributed with SSR examples.

SSR Best Practices

• Use declarative Shadow DOM when encapsulated SSR markup is needed.
• Render meaningful fallback content inside custom element tags.
• Pass simple server data through attributes.
• Guard hydration logic against double initialization.
• Keep server and client render output consistent.
• Load component definition scripts as modules on the client.
• Test with slow networks and JavaScript disabled.

Common SSR Mistakes

• Rendering empty custom elements with no server content.
• Calling attachShadow() when a declarative root already exists.
• Assuming SSR alone makes components interactive.
• Relying on properties instead of attributes for initial server data.
• Creating hydration mismatches between server and client HTML.
• Hiding all content inside JS-only shadow rendering.
• Ignoring browser support for declarative Shadow DOM.

Key Takeaways

• Web Components can be server-rendered, but still need client upgrade.
• Declarative Shadow DOM is key for encapsulated SSR markup.
• Attributes and slotted content make SSR data passing practical.
• Hydration attaches interactivity to existing server HTML.
• Good SSR improves first paint, SEO, and progressive enhancement.