{"id":16666500,"url":"https://github.com/patricknelson/svelte-retag","last_synced_at":"2025-04-02T20:08:55.515Z","repository":{"id":172037471,"uuid":"636065289","full_name":"patricknelson/svelte-retag","owner":"patricknelson","description":"Light DOM custom element wrapper for Svelte 3 and 4 with slots, context and Vite HMR support","archived":false,"fork":false,"pushed_at":"2024-09-29T21:54:35.000Z","size":1105,"stargazers_count":41,"open_issues_count":9,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-24T04:42:30.536Z","etag":null,"topics":["context","custom-elements","hmr","slots","svelte","web-components"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/svelte-retag","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"crisward/svelte-tag","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patricknelson.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":"2023-05-04T03:52:37.000Z","updated_at":"2025-03-11T15:03:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"2de902bc-8da6-43bf-a44d-69f69af3eb97","html_url":"https://github.com/patricknelson/svelte-retag","commit_stats":null,"previous_names":["patricknelson/svelte-tag"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricknelson%2Fsvelte-retag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricknelson%2Fsvelte-retag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricknelson%2Fsvelte-retag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricknelson%2Fsvelte-retag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patricknelson","download_url":"https://codeload.github.com/patricknelson/svelte-retag/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246884767,"owners_count":20849554,"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":["context","custom-elements","hmr","slots","svelte","web-components"],"created_at":"2024-10-12T11:11:09.784Z","updated_at":"2025-04-02T20:08:55.497Z","avatar_url":"https://github.com/patricknelson.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"logo/svelte-retag.svg\" width=\"348\"\u003e\n\n# svelte-retag\n\n![Unit Tests](https://github.com/patricknelson/svelte-retag/actions/workflows/unit-tests.yml/badge.svg)\n\nA web component wrapper for Svelte 3 and 4. Embeds your Svelte app or components inside custom elements using the light\nDOM _or_ shadow DOM. Automatically forwards all slots and attributes to your Svelte app.\n\n**Demo:** https://svelte-retag.vercel.app/\n\n## Core Features\n\n* 🌟 **Light DOM:** Allows you to render your Svelte components as custom elements in the light DOM as usual.\n* 🎰 **Slots \u0026 Nesting:** Supports default and named slots in the _light DOM_ (with nesting).\n* 🧭 **Context:** Use `setContext()` and `getContext()` and just compose your components as custom elements as you\n\tnormally would ([see live tab demo](https://svelte-retag.vercel.app/)). Supports nesting.\n* ⚡ **Vite HMR:** Unlike Svelte, these custom elements are also compatible with Vite's HMR. It avoids the\n\tinfamous `Failed to execute 'define' on 'CustomElementRegistry'` errors.\n* 🏃‍♂️ **IIFE/UMD:** Supports building to `iife` and `umd` for eager rendering to the light DOM, as soon as the\n\tparser encounters the custom element. Reduces CLS (Cumulative Layout Shift), making it interactive more quickly\n\t_without_ waiting for `defer`'d scripts (such as modules).\n* ⚙ **Composability:** `svelte-retag` gives you the flexibility to use your component as you normally would within\n\tSvelte _and_ as a custom element outside of Svelte (supporting both `\u003cExampleComponent /\u003e` and `\u003cexample-component\u003e`).\n\tFor details on how to use with PHP, Python, Ruby, etc., see [Backend Integration](#backend-integration) below.\n* 💼 **Portability:** Enables the freedom to utilize your Svelte components anywhere custom elements are supported,\n\tregardless of the stack (great for upgrading legacy applications).\n\n## Why?\n\nSvelte already allows you to compile your components to custom elements. However, it's missing a few extra features:\n\n* Svelte 3: You have to use shadow DOM (no light DOM compatibility at all)\n* Svelte 4: You cannot use slots in the light DOM (https://github.com/sveltejs/svelte/issues/8963), which also means no\n\tnesting of your web components\n* No context support (https://github.com/sveltejs/svelte/issues/8987)\n* Vite HMR doesn't work with custom elements (https://github.com/sveltejs/svelte/issues/8681\n\tand https://github.com/sveltejs/svelte-hmr/issues/26)\n\n## How do I use it?\n\n### Installation \u0026 Quick Start\n\n```bash\nnpm install svelte-retag\n```\n\nCheck out the [Hello World demo](https://github.com/patricknelson/svelte-retag/tree/main/demo/hello-world) to see it\nin action yourself and for instructions on how to get started from scratch.\n\n### \u003ca id=\"backend-integration\" /\u003eBackend Integration\n\nIf you're running a non-JavaScript backend such as PHP, Python, Ruby, etc. and would still like to use Vite (but cannot\nrely solely on Vite for local development),\nsee [Vite's Backend Integration documentation](https://vitejs.dev/guide/backend-integration.html).\nThis will guide you on how to run both your specific backend _and_ Vite's development server simultaneously.\n\n#### Svelte vs. SvelteKit\n\nNote that if you already have an existing backend, it is recommended that you just install `svelte` and not\n`@sveltejs/kit` since the extra metaframework features of SvelteKit (such as routing) may not be necessary. SvelteKit is\nnow installed by default in the official documentation, so the extra complexity may be confusing when you are already\nrunning a backend and just using `svelte-retag` to add web components into an existing site.\n\n### Demo Code\n\nAdd the following to your main entrypoint. If you are using Vite, this would likely be `src/main.js`.\n\n```javascript\nimport svelteRetag from 'svelte-retag';\nimport HelloWorld from './HelloWorld.svelte';\n\nsvelteRetag({\n\tcomponent: HelloWorld,\n\ttagname: 'hello-world',\n\n\t// Optional:\n\tattributes: true, // Forward all attributes to your component, or set to explicit list of attributes, e.g. ['greetperson'] or leave empty\n\tshadow: false, // Use the light DOM\n\thref: '/your/stylesheet.css', // Only necessary if shadow is true\n});\n```\n\nAnd in the `HelloWorld.svelte` Svelte component:\n\n```svelte\n\u003cscript\u003e\n\texport let greetPerson = 'World';\n\u003c/script\u003e\n\n\u003ch1\u003eHello {greetPerson}!\u003c/h1\u003e\n```\n\nNow anywhere you use the `\u003chello-world\u003e` tag, you'll get a Svelte component. Note that you must set your tag\nname\nto [anything containing a dash](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements).\n\nTo align with Svelte 4, **attributes** are automatically converted to lowercase (following\nthe [Lit-style naming convention](https://lit.dev/docs/components/properties/#observed-attributes)). So, `greetPerson`\non your component would be automatically made available as `greetperson` on your custom element.\n\n```html\n\n\u003chello-world greetperson=\"Cris\"\u003e\u003c/hello-world\u003e\n```\n\nFor more info on getting started, take a look at\nthe [Hello World demo](https://github.com/patricknelson/svelte-retag/tree/main/demo/hello-world).\n\n### Options 🛠\n\n| Option                        |   Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n|-------------------------------|:------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `component`                   | _(required)_ | The constructor for your Svelte component (from `import`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| `tagname`                     | _(required)_ | The custom element tag name to use ([must contain a dash](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `attributes`                  |     `[]`     | `Array` (legacy): Explicit list of attributes to reactively forward to your component. Attributes must be the lowercase version of your Svelte component props ([similar to Lit](https://lit.dev/docs/components/properties/#observed-attributes)). \u003cbr\u003e\u003cbr\u003e `Boolean` (recommended): If set to `true`, will automatically forward all attributes to your component props. If `false`, will not forward anything. \u003cbr\u003e\u003cbr\u003e **Note:** In v2, this option will be removed and all attributes will be forwarded by default (for consistency with Svelte 4's custom elements, see https://github.com/patricknelson/svelte-retag/issues/36). |\n| `shadow`                      |   `false`    | Optional. Indicates if this component should use shadow DOM. \u003cbr/\u003e\u003cbr/\u003e **Note:** Only basic support for shadow DOM is currently provided. See https://github.com/patricknelson/svelte-retag/issues/6.                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| `ignoreCommonAttribWarnings`  |   `false`    | Optional. Suppresses warnings in development mode about common attributes (such as `id`, `class`, `style` and `data-*`) if they don't already exist on the component. Set to an array to customize the list of ignored attributes.\n| `href`                        |     `''`     | Optional. URL to your stylesheet. Allows you to ensure your styles are included in the shadow DOM. This option is only useful when `shadow` is set to `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n\n**Note:** For portability, `svelte-retag`'s API is fully backward compatible\nwith [`svelte-tag@^1.0.0`](https://github.com/crisward/svelte-tag).\n\n\n\u003cdetails\u003e\n\u003csummary\u003eFor experimental options, click here.\u003c/summary\u003e\n\n### Experimental Options 👨‍🔬\n\n⚠ **Warning: These features are not production ready and are purely experimental.** ⚠\n\n| Option       | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n|--------------|:-------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `hydratable` | `false` | Optional. Compatible with Light DOM rendering only. \u003cbr\u003e\u003cbr\u003e If enabled, allows for SSR/SSG of custom elements managed by `svelte-retag` by including extra markup so that they can be initialized client-side from pre-rendered HTML (a.k.a. \"hydrated\").  See [hydration demo here](https://svelte-retag.vercel.app/hydratable.html). \u003cbr\u003e\u003cbr\u003e **Do not** enable this for regular use on the front-end. Enable this _**only**_ during SSR/SSG to allow for proper initialization and **only** if you plan on re-rendering a second time (e.g. first in SSG/SSR _and then_ finally in-browser). \u003cbr\u003e\u003cbr\u003e **Why does this exist?** \u003cbr\u003e\u003cbr\u003e The initial use case for this is to address rendering bugs in [Percy](https://percy.io) which renders the components 2 times (first in a local headless _Chrome browser_, then a second time in the cloud). |\n\n\u003c/details\u003e\n\n## Change Log\n\n### v1\n\nChanges since forking from [`svelte-tag`](https://github.com/crisward/svelte-tag) (upstream):\n\n- Migrate to Vitest for unit testing (see https://github.com/crisward/svelte-tag/pull/14)\n- Update logo\n- Fix nested slot support (https://github.com/patricknelson/svelte-retag/pull/5)\n- Better support for slots during early execution of IIFE compiled packages, i.e. use `MutationObserver` to watch\n\tfor light DOM slots during initial parsing (see https://github.com/patricknelson/svelte-retag/issues/7)\n- Support Lit-style lowercase props (see https://github.com/patricknelson/svelte-retag/pull/9)\n- Svelte 4 support (tested)\n- Support context (see https://github.com/patricknelson/svelte-retag/issues/10, PR\n\tat https://github.com/patricknelson/svelte-retag/pull/18)\n- Add demos to vercel site (see https://github.com/patricknelson/svelte-retag/issues/11)\n- Add step-by-step instructions and provided a simple MVP\n\texample (https://github.com/patricknelson/svelte-retag/pull/24)\n- Automatically forward all attributes to component (i.e. `attributes: true`) (https://github.com/patricknelson/svelte-retag/issues/34)\n- Add better TypeScript support (https://github.com/patricknelson/svelte-retag/pull/33)\n- Add ability to suppress warnings for common attributes (such as `id`, `class`, `style` and `data-*`) if they don't\n  already exist on the component (https://github.com/patricknelson/svelte-retag/pull/54)\n\n### v2\n\nSee the **[milestones page](https://github.com/patricknelson/svelte-retag/milestones)** for changes planned in upcoming\nversions. Please be aware that until the version is officially released, the features slated for a particular version\nare subject to change!\n\n## Support \u0026 Contribution\n\n**Features:** The API for this package is intentionally minimal and features that are outside of the scope of the core\nfeatures listed above are not likely to be considered. However, for stability (and due to time constraints), new\nfeatures\nwill still be considered if they are small or will have little or no impact on _existing_ functionality.\n\nTo report bugs or improvements, please [open an issue](https://github.com/patricknelson/svelte-retag/issues) and explain\nin as much detail as possible what the bug is and how to reproduce it. Please make sure that you only submit an\nissue if you have verified that it requires a change to `svelte-retag` itself.\n\n**PR's:** If you'd like to contribute, please feel free to open a PR, **however**: If possible, please attach it to an\nexisting\nissue to ensure that discussion regarding your pull request isn't lost (in case it cannot be merged for whatever\nreason).\n\n## Attribution\n\n* Logo - Rich Harris, MIT \u003chttp://opensource.org/licenses/mit-license.php\u003e, via Wikimedia Commons\n* [`svelte-tag`](https://github.com/crisward/svelte-tag) - Chris Ward ([@crisward](https://github.com/crisward)). This\n\tpackage was forked and modified from https://github.com/crisward/svelte-tag (thus the \"re\" in `svelte-retag`).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatricknelson%2Fsvelte-retag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatricknelson%2Fsvelte-retag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatricknelson%2Fsvelte-retag/lists"}