https://github.com/slogsdon/javascript-web-component-hydration
Thin wrapper around HTMLElement to support hydration of server-side rendered custom elements
https://github.com/slogsdon/javascript-web-component-hydration
server-side-rendering web-components
Last synced: 2 months ago
JSON representation
Thin wrapper around HTMLElement to support hydration of server-side rendered custom elements
- Host: GitHub
- URL: https://github.com/slogsdon/javascript-web-component-hydration
- Owner: slogsdon
- License: mit
- Created: 2019-08-04T23:02:26.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2019-08-06T04:09:17.000Z (almost 6 years ago)
- Last Synced: 2025-03-26T18:35:29.527Z (3 months ago)
- Topics: server-side-rendering, web-components
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/web-component-hydration
- Size: 9.77 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# web-component-hydration
> Thin wrapper around HTMLElement to support hydration of server-side rendered custom elements
### Features
- Plain JavaScript
- Native [web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
- Minimal dependencies
### Reasoning
JavaScript is readily available and flexible. Modern browser JavaScript is more than capable.
This project also scratches an itch to see how much JavaScript and non-Node.js server environments can work together to handle this problem domain.
## Client-Side Components
Let's dive in quickly to see how the client-side JavaScript looks:
```javascript
// x-list-item.js
import { CustomHTMLElement } from './node_modules/web-component-hydration/custom-html-element.js';
export class XListItem extends CustomHTMLElement {
// define `XListItem`'s tag name
static get is() { return 'x-list-item'; }
}
```
```javascript
// main.js
import { hydrate } from './node_modules/web-component-hydration/helpers.js';
import { XListItem } from './x-list-item.js';
// register `XListItem` as a custom element
await XListItem.register();
// hydrate any server-side rendered `XListIem`s
hydrate(XListItem.is);
```
A couple of key points:
- **`CustomHTMLElement.is`** defines the element's tag name
- **`CustomHTMLElement.register`** ensures an element is able to be defined and is only defined once
- **`hydrate`** operates on all server-side rendered elements with a given tag name and is called internally by `CustomHTMLElement.connectedCallback` to hydrate children
## Server-Side Rendering
This library is meant to be paired with a service to render custom elements / web components on the server. If a libary for your preferred language isn't available, most languages have support built-in or via third-party packages to convert custom element templates and some data to static HTML.
Example template for the `x-list-item` custom element:
```html
```
Rendered HTML with data `content`:
```html
content
```
A few things to notice:
- The data (`content`) is set as the `data-initial-data` attribute's value and inserted into the unnamed slot as a child
- The custom element name (`x-list-item`) is set as the `data-template` attribute's value
This `data-template` attribute matches the `template` via `id="template-x-list"`, allowing the client library to know which template to use during hydration.
### Named Slots
Using named slots in the custom element's template requires a couple of small changes when compared to the single unnamed slot:
- Slots should be named, and named slots should not be mixed with unnamed slots. These should match browser specs
- `data-initial-data` should be URL-encoded JSON, representing key/value pairs for each of the named slots
As an example:
```html
```
Rendered HTML with data `content`:
```html
content
bar
```
### Known Implementations
- [PHP](https://packagist.org/packages/slogsdon/web-component-ssr)
## License
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.