---
title: Server-Side Rendering
slug: wip/server-side-rendering
createdAt: 2023-07-21T06:22:50.493Z
---

# Server-Side Rendering

:::hint{type="info"}
Cosmos Components are built on top of the Web Components standard utilizing Shadow DOM. While Shadow DOM is great for isolating a component's DOM and styles, it comes with its own unique challenge for applications that pre-render pages on the server.
:::

Since Shadow DOM and Web Components as a whole are a Browser API, they don't exist in a server environment. This means that, without any intervention, the components would arrive empty and without any functionality or styling on the client, resulting in a flash of unstyled content until they get hydrated on the client.

This means having to produce a light DOM version of the components on the server in order to reconstruct the Shadow DOM and scoped styles during the rendering process.&#x20;

Stencil recently started leveraging **Declarative Shadow DOM (DSD)** to optimize the pre-rendering and hydration process of Cosmos web components. DSD allows the Shadow DOM structure to be serialized on the server and preserved as part of the document. This enables consistent component isolation and style scoping while improving performance and compatibility.

## Usage

The `@cosmos/web` library includes a `hydrate` script that can be used in two different ways: `hydrateDocument` and `renderToString`.

### renderToString

Allows to pass in a HTML string that also returns a promise of `HydrateResults`. The second parameter is a config object that can alter the output of the markup. The resulting string can be parsed from the `html` property.

:::CodeblockTabs
index.ts

```typescript
import type { HydrateResults } from '@cosmos/web/hydrate';
import { renderToString } from '@cosmos/web/hydrate';

const results: HydrateResults = await renderToString(html, { 
  serializeShadowRoot: "scoped" 
});

console.log(results.html);
```
:::



| Option                | Type                                                                            | Default                | Description                                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| approximateLineWidth  | number                                                                          |                        | Determines when line breaks are set while serializing the component.                                                                          |
| prettyHtml            | boolean                                                                         | false                  | If set to true, prettifies the serialized HTML code, indents elements, and escapes text nodes.                                                |
| removeAttributeQuotes | boolean                                                                         | false                  | If set to true, removes attribute quotes when possible, e.g., changes `someAttribute="foo"` to `someAttribute=foo`.                           |
| removeEmptyAttributes | boolean                                                                         | true                   | If set to true, removes attributes that don't have values, e.g., removes `class=""`.                                                          |
| removeHtmlComments    | boolean                                                                         | false                  | If set to true, removes abundant HTML comments. Stencil still inserts hydration comments for reconciliation.                                  |
| beforeHydrate         | (document: Document, url: URL) => void \| Promise                               |                        | Allows modification of the document and its components before the hydration process starts.                                                   |
| afterHydrate          | (document: Document, url: URL, results: PrerenderUrlResults) => void \| Promise |                        | Allows modification of the document and its components after the virtual DOM rendering but before the serialization process starts.           |
| serializeShadowRoot   | "scoped" \| "declarative-shadow-dom"                                            | declarative-shadow-dom | Configures how the components should be rendered on the server, e.g. as Declarative Shadow DOM, as scoped components or as a mixture of both. |



### hydrateDocument

It is also possible to use `hydrateDocument` as a part of your server's response logic before serving the web page.`hydrateDocument` takes two arguments, a [document](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument), and an `options` object. The function returns a promise with the hydrated results.

We now also expose the `createWindowFromHtml` method which allows you to create a node friendly `DOM` implementation, allowing you to manipulate and render on the server. This can be used instead of other JavaScript implementation of web-browser, such as `happy-dom` and `domino`

:::CodeblockTabs
createWindowFromHtml

```typescript
// server
import { hydrateDocument, createWindowFromHtml } from "@cosmos/web/hydrate";

function hydrate(template: string) {
	const win = createWindowFromHtml(template, 'unique-id'));
	const document = win.document
	
	const result = await hydrateDocument(document, {
		// hydrateDocument config options
	})

	// Result is just for diagnostic, `document` is transformed in place. 
	if (result.diagnostics.length > 0) {
		result.diagnostics.forEach((diagnostic) => {
			console.error({ message: 'hydration failed', diagnostic });
		});
	}

	// Serialize 
	return `<!doctype html> ${document.documentElement.outerHTML}`;
}

hydrate(/*html*/)
```

happy-dom

```typescript
// server
import { type Document, Window } from 'happy-dom';
import { hydrateDocument } from "@cosmos/web/hydrate";

// Happy Dom is a lightweight DOM implementation that can be used to create a document to hydrate.
// Supports DSD.
 async function createDocumentToHydrate(html: string): Promise<Document> {
    const window = new Window();
    const document = window.document;
    document.write(html);
    await window.happyDOM.waitUntilComplete();
    return document;
}

async function hydrate(template: string){
    const document = await createDocumentToHydrate(html);
    const result = await hydrateDocument(document, {
	    serializeShadowRoot: "scoped"
    })
  
  	// Result is just for diagnostic, `document` is transformed in place. 
	if (result.diagnostics.length > 0) {
		result.diagnostics.forEach((diagnostic) => {
			console.error({ message: 'hydration failed', diagnostic });
		});
	}
    // Serialize 
    return `<!doctype html> ${document.documentElement.outerHTML}`;
}

hydrate(/*html*/)
```
:::

| Option                    | Type                                 | Description                                                                                                                                   |
| ------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| canonicalUrl              | string                               | Sets the canonical URL for the document.                                                                                                      |
| constrainTimeouts         | boolean                              | Constrains `setTimeout()` and `setInterval()` to 1ms. Defaults to true.                                                                       |
| clientHydrateAnnotations  | boolean                              | Includes HTML comments and attributes for client-side hydration. Defaults to true.                                                            |
| cookie                    | string                               | Sets `document.cookie`.                                                                                                                       |
| direction                 | string                               | Sets the `dir` attribute for text direction on the `<html>` element.                                                                          |
| language                  | string                               | Sets the `lang` attribute on the `<html>` element.                                                                                            |
| maxHydrateCount           | number                               | Specifies the maximum number of components to hydrate. Defaults to 300.                                                                       |
| referrer                  | string                               | Sets `document.referrer`.                                                                                                                     |
| removeScripts             | boolean                              | Removes `<script>` elements from the document. Defaults to false.                                                                             |
| removeUnusedStyles        | boolean                              | Removes unused CSS from the document. Defaults to true.                                                                                       |
| resourcesUrl              | string                               | Specifies the base URL for loading resources such as assets.                                                                                  |
| timeout                   | number                               | The time in milliseconds to wait for hydration before a timeout error occurs. Defaults to 15000.                                              |
| title                     | string                               | Sets `document.title`.                                                                                                                        |
| url                       | string                               | Sets `location.href` for the document.                                                                                                        |
| userAgent                 | string                               | Sets `navigator.userAgent`.                                                                                                                   |
| <br />serializeShadowRoot | "scoped" \| "declarative-shadow-dom" | Configures how the components should be rendered on the server, e.g. as Declarative Shadow DOM, as scoped components or as a mixture of both. |



:::hint{type="warning"}
[DSD](https://web.dev/articles/declarative-shadow-dom) improves the balance between Shadow DOM isolation and server-side rendering by allowing encapsulated components to be serialized and hydrated seamlessly. By setting `serializeShadowRoot` to `declarative-shadow-dom`, this behavior can be enabled since `@cosmos/web@11.0.0 `but is **experimental and not recommended for production use.**
:::

### ⚠️ Important Considerations

The experimental Declarative Shadow DOM support has known limitations that prevent production use:

- &#x20;Server-side hydration takes significantly longer to complete
- The current DSD standard implementation duplicates styles for each component instance (e.g., multiple cosmos-text components will inject duplicate styles), resulting in substantially increased response sizes
- Overall performance may be negatively impacted in component-heavy applications.


We will continue monitoring developments in this area and provide updates as the standard matures and these limitations are addressed.



