Known issue for SSR/SSG Rendering

[vtnorton]

This document outlines our focused tasks to enable SuperViz to run with full compatibility on SSR/SSG frameworks such as Next.js. Nothing is set in stone, but we will strive to complete these tasks in a reasonable timeframe.

[carlossantos74]

Overview

The SuperViz SDK will undergo architectural enhancements to enable native support for Server-Side Rendering (SSR) and Static Site Generation (SSG). These improvements are crucial to ensure compatibility with SSR-native frameworks like Nuxt and Next.js.

What's SSR?

Server-Side Rendering (SSR) in Next.js is a technique where a web page's HTML is generated on the server before being sent to the client's browser. When a user requests a page, Next.js creates the HTML on the server and sends it fully rendered to the client, allowing for a fast initial display. JavaScript is then loaded in the background to make the page interactive, a process called hydration. This contrasts with Client-Side Rendering (CSR), where the browser initially receives minimal HTML and then fetches and renders content using JavaScript.

What's SSG?

Static Site Generation (SSG) is another rendering strategy supported by frameworks like Next.js and Nuxt. In SSG, HTML pages are generated at build time, rather than on each request as with SSR. This approach is ideal for content that doesn't change frequently. When a user requests a page, the pre-generated HTML is served directly from a CDN, resulting in extremely fast load times. SSG combines the benefits of static sites—speed, security, and reliability—with the dynamic capabilities of modern JavaScript frameworks.

What are the Problems with SSR/SSG Today?

One approach SuperViz uses to distribute visual components, such as Contextual Comments, is through web components, leveraging the lit library.

The main challenge is that web components are not natively compatible with Static Site Generation (SSG) and Server-Side Rendering (SSR). Since web components are essentially custom HTML elements, they rely on browser-specific APIs for their creation. This dependency prevents the SuperViz SDK from running natively in frameworks like Next.js, which focus on server-side operations.

When attempting to generate static pages that include SuperViz components, you might encounter an error like this:

This error occurs because the HTMLElement class, which is integral to the web components API, is not available in the Node.js environment where SSG and SSR typically run. Essentially, the error indicates that the code is trying to use or extend HTMLElement, but this class doesn't exist in the current context.

This issue underscores the fundamental incompatibility between web components, which are designed to run in browsers, and server-side JavaScript environments. Frameworks like Next.js, which aim to provide seamless SSR and SSG capabilities, face challenges when integrating libraries that heavily rely on browser-specific APIs.

To overcome this limitation, developers often need to implement workarounds such as:

export const dynamic = "force-dynamic";

export default function Layout({
 children,
}: Readonly<{children: React.ReactNode}>) {
  return children;
}

This approach prevents the issue by forcing Next.js to skip the pre-compilation step, ensuring that the page is generated solely on the client side. You can read more about this approach here.

---

We recognize the challenges posed by integrating web components with SSR and SSG frameworks like Next.js. To address these issues, we are committed to implementing a series of improvements in the SuperViz SDK that will enable native support for these frameworks. Our goal is to provide seamless compatibility, allowing developers to leverage the full power of SSR and SSG without encountering the current limitations.