{"id":13341609,"url":"https://github.com/slogsdon/javascript-web-component-hydration","last_synced_at":"2025-04-13T00:34:30.407Z","repository":{"id":141996361,"uuid":"200549943","full_name":"slogsdon/javascript-web-component-hydration","owner":"slogsdon","description":"Thin wrapper around HTMLElement to support hydration of server-side rendered custom elements","archived":false,"fork":false,"pushed_at":"2019-08-06T04:09:17.000Z","size":10,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T18:35:29.527Z","etag":null,"topics":["server-side-rendering","web-components"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/web-component-hydration","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slogsdon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-04T23:02:26.000Z","updated_at":"2024-09-22T19:09:18.000Z","dependencies_parsed_at":"2023-07-22T01:15:33.448Z","dependency_job_id":null,"html_url":"https://github.com/slogsdon/javascript-web-component-hydration","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slogsdon%2Fjavascript-web-component-hydration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slogsdon%2Fjavascript-web-component-hydration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slogsdon%2Fjavascript-web-component-hydration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slogsdon%2Fjavascript-web-component-hydration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slogsdon","download_url":"https://codeload.github.com/slogsdon/javascript-web-component-hydration/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650490,"owners_count":21139670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["server-side-rendering","web-components"],"created_at":"2024-07-29T19:25:39.156Z","updated_at":"2025-04-13T00:34:30.380Z","avatar_url":"https://github.com/slogsdon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# web-component-hydration\n\n\u003e Thin wrapper around HTMLElement to support hydration of server-side rendered custom elements\n\n### Features\n\n- Plain JavaScript\n- Native [web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)\n- Minimal dependencies\n\n### Reasoning\n\nJavaScript is readily available and flexible. Modern browser JavaScript is more than capable.\n\nThis project also scratches an itch to see how much JavaScript and non-Node.js server environments can work together to handle this problem domain.\n\n## Client-Side Components\n\nLet's dive in quickly to see how the client-side JavaScript looks:\n\n```javascript\n// x-list-item.js\nimport { CustomHTMLElement } from './node_modules/web-component-hydration/custom-html-element.js';\n\nexport class XListItem extends CustomHTMLElement {\n  // define `XListItem`'s tag name\n  static get is() { return 'x-list-item'; }\n}\n```\n\n```javascript\n// main.js\nimport { hydrate } from './node_modules/web-component-hydration/helpers.js';\nimport { XListItem } from './x-list-item.js';\n\n// register `XListItem` as a custom element\nawait XListItem.register();\n// hydrate any server-side rendered `XListIem`s\nhydrate(XListItem.is);\n```\n\nA couple of key points:\n\n- **`CustomHTMLElement.is`** defines the element's tag name\n- **`CustomHTMLElement.register`** ensures an element is able to be defined and is only defined once\n- **`hydrate`** operates on all server-side rendered elements with a given tag name and is called internally by `CustomHTMLElement.connectedCallback` to hydrate children\n\n## Server-Side Rendering\n\nThis 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.\n\nExample template for the `x-list-item` custom element:\n\n```html\n\u003ctemplate id=\"template-x-list-item\"\u003e\n  \u003cli\u003e\n    \u003cslot\u003e\u003c/slot\u003e\n  \u003c/li\u003e\n\u003c/template\u003e\n```\n\nRendered HTML with data `content`:\n\n```html\n\u003cdiv data-template=\"x-list-item\" data-initial-data=\"content\"\u003e\n  \u003cli\u003e\n    \u003cslot\u003econtent\u003c/slot\u003e\n  \u003c/li\u003e\n\u003c/div\u003e\n```\n\nA few things to notice:\n\n- The data (`content`) is set as the `data-initial-data` attribute's value and inserted into the unnamed slot as a child\n- The custom element name (`x-list-item`) is set as the `data-template` attribute's value\n\nThis `data-template` attribute matches the `template` via `id=\"template-x-list\"`, allowing the client library to know which template to use during hydration.\n\n### Named Slots\n\nUsing named slots in the custom element's template requires a couple of small changes when compared to the single unnamed slot:\n\n- Slots should be named, and named slots should not be mixed with unnamed slots. These should match browser specs\n- `data-initial-data` should be URL-encoded JSON, representing key/value pairs for each of the named slots\n\nAs an example:\n\n```html\n\u003ctemplate id=\"template-x-list-item\"\u003e\n  \u003cli\u003e\n    \u003cslot name=\"label\"\u003e\u003c/slot\u003e\n    \u003cslot name=\"foo\"\u003e\u003c/slot\u003e\n  \u003c/li\u003e\n\u003c/template\u003e\n```\n\nRendered HTML with data `content`:\n\n```html\n\u003cdiv data-template=\"x-list-item\" data-initial-data=\"%7B%22label%22%3A%22content%22%2C%22foo%22%3A%22bar%22%7D\"\u003e\n  \u003cli\u003e\n    \u003cslot name=\"label\"\u003econtent\u003c/slot\u003e\n    \u003cslot name=\"foo\"\u003ebar\u003c/slot\u003e\n  \u003c/li\u003e\n\u003c/div\u003e\n```\n\n### Known Implementations\n\n- [PHP](https://packagist.org/packages/slogsdon/web-component-ssr)\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslogsdon%2Fjavascript-web-component-hydration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslogsdon%2Fjavascript-web-component-hydration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslogsdon%2Fjavascript-web-component-hydration/lists"}