Skip to content

Commit 7023232

Browse files
patricknelsonpatricknelson
authored
Merge pull request #24 from patricknelson/issue-23-example-docs
Fix for #23: Better documentation explaining how to get started
2 parents 4ba67d6 + 3b8f29a commit 7023232

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1114
-41
lines changed

‎README.md

Lines changed: 85 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -9,64 +9,115 @@ DOM _or_ shadow DOM. Automatically forwards all slots and attributes to your Sve
99

1010
**Demo:** https://svelte-retag.vercel.app/
1111

12-
## Core features
12+
## Core Features
1313

1414
* 🌟 **Light DOM:** Allows you to render your Svelte components as custom elements in the light DOM as usual.
15-
* 🎰 **Slots:** Supports default and named slots in the _light DOM_ (supports nesting).
15+
* 🎰 **Slots & Nesting:** Supports default and named slots in the _light DOM_ (with nesting).
1616
* 🧭 **Context:** Use `setContext()` and `getContext()` and just compose your components as custom elements as you
1717
normally would ([see live tab demo](https://svelte-retag.vercel.app/)). Supports nesting.
1818
* ⚡ **Vite HMR:** Unlike Svelte, these custom elements are also compatible with Vite's HMR. It avoids the
1919
infamous `Failed to execute 'define' on 'CustomElementRegistry'` errors.
2020
* 🏃‍♂️ **IIFE/UMD:** Supports building to `iife` and `umd` for eager rendering to the light DOM, as soon as the
2121
parser encounters the custom element. Reduces CLS (Cumulative Layout Shift), making it interactive more quickly
22-
_without_ waiting for `defer`'d scripts (such as modules).
23-
* ⚙ **Composability:** `svelte-retag` gives you the flexility to use your component as you normally would within Svelte
24-
_and_ as a custom element outside of Svelte (supporting both `<ExampleComponent />` and `<example-component>`).
22+
_without_ waiting for `defer`'d scripts (such as modules).
23+
* ⚙ **Composability:** `svelte-retag` gives you the flexibility to use your component as you normally would within
24+
Svelte _and_ as a custom element outside of Svelte (supporting both `<ExampleComponent />` and `<example-component>`).
25+
For details on how to use with PHP, Python, Ruby, etc., see [Backend Integration](#backend-integration) below.
2526
* 💼 **Portability:** Enables the freedom to utilize your Svelte components anywhere custom elements are supported,
2627
regardless of the stack (great for upgrading legacy applications).
2728

2829
## Why?
2930

3031
Svelte already allows you to compile your components to custom elements. However, it has a couple of flaws:
3132

32-
* All of your nested components have to be implemented as custom elements, since the render flag applies to everything.
33-
* You have to use shadow DOM (Svelte 3, or Svelte 4 if you still want to use slots).
34-
* You have to deal with lots of bugs.
35-
* You loose many features Svelte has for inter-component communication.
33+
* Svelte 3: You have to use shadow DOM (no light DOM compatibility at all)
34+
* Svelte 4: You cannot use slots in the light DOM (https://github.com/sveltejs/svelte/issues/8963), which means no nesting
35+
* No context support (https://github.com/sveltejs/svelte/issues/8987)
36+
* Vite HMR doesn't work with custom elements (see comments of https://github.com/sveltejs/svelte/issues/8681)
3637

3738
## How do I use it?
3839

39-
### Installation
40+
### Installation & Quick Start
4041

4142
```bash
4243
npm install svelte-retag
4344
```
4445

45-
### Demo code
46+
If you're **starting from scratch**, create a new [Vite](https://vitejs.dev/) project like so:
47+
48+
1. `npm create vite@latest` and select `Svelte` as your framework and `JavaScript` as your variant (or `TypeScript` if
49+
you prefer). Don't select `SvelteKit` if you're already running another backend (e.g. PHP or Python, [see below](#backend-integration)).
50+
2. `cd` into your new project
51+
3. Run `npm install svelte-retag`
52+
4. Run `npm run dev` to start the Vite development server and open http://localhost:5173/ in your browser
53+
5. Create your Svelte components and define your custom elements (web components) using `svelteRetag()` in `src/main.js` as described below, e.g.
54+
55+
```javascript
56+
import svelteRetag from 'svelte-retag';
57+
import HelloWorld from './HelloWorld.svelte';
58+
59+
svelteRetag({
60+
component: HelloWorld,
61+
tagname: 'hello-world',
62+
});
63+
```
64+
6. In `index.html`, remove `<div id="app"></div>` and instead add your custom elements to your `index.html` (e.g.
65+
`<hello-world greetperson="👩‍🚀"></hello-world>`).
66+
67+
**Note:** No modifications are required to your `vite.config.js` or `svelte.config.js` files. Keep in mind that the
68+
`customElement` compiler option _does not_ need to be enabled since we are replacing that functionality entirely
69+
with `svelte-retag`.
70+
71+
### <a id="backend-integration" />Backend Integration
72+
73+
If you're running a non-JavaScript backend such as PHP, Python, Ruby, etc. and would still like to use Vite (but cannot
74+
rely solely on Vite for local development), see [Vite's Backend Integration documentation](https://vitejs.dev/guide/backend-integration.html).
75+
This will guide you on how to run both your specific backend _and_ Vite's development server simultaneously.
76+
77+
#### Svelte vs. SvelteKit
78+
79+
Note that if you already have an existing backend, it is recommended that you just install `svelte` and not
80+
`@sveltejs/kit` since the extra metaframework features of SvelteKit (such as routing) may not be necessary. SvelteKit is
81+
now installed by default in the official documentation, so the extra complexity may be confusing when you are already
82+
running a backend and just using `svelte-retag` to add web components into an existing site.
83+
84+
### Demo Code
85+
86+
Add the following to your main entrypoint. If you are using Vite, this would likely be `src/main.js`.
4687
4788
```javascript
4889
import svelteRetag from 'svelte-retag';
49-
import HelloWorld from 'hello-world.svelte';
90+
import HelloWorld from './HelloWorld.svelte';
5091
5192
svelteRetag({
5293
component: HelloWorld,
5394
tagname: 'hello-world',
5495
5596
// Optional:
56-
attributes: ['greetperson'],
57-
shadow: false,
97+
attributes: ['greetperson'], // Changes to these attributes will be reactively forwarded to your component
98+
shadow: false, // Use the light DOM
5899
href: '/your/stylesheet.css', // Only necessary if shadow is true
59100
60101
// Experimental:
61102
hydratable: false,
62103
});
63104
```
64105
106+
And in the `HelloWorld.svelte` Svelte component:
107+
108+
```svelte
109+
<script>
110+
export let greetPerson = 'World';
111+
</script>
112+
113+
<h1>Hello {greetPerson}!</h1>
114+
```
115+
65116
Now anywhere you use the `<hello-world>` tag, you'll get a Svelte component. Note that you must set your tag
66117
name
67118
to [anything containing a dash](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements).
68119

69-
To align with future versions of Svelte, attributes are automatically converted to lowercase (following
120+
To align with Svelte 4, **attributes** are automatically converted to lowercase (following
70121
the [Lit-style naming convention](https://lit.dev/docs/components/properties/#observed-attributes)). So, `greetPerson`
71122
on your component would be automatically made available as `greetperson` on your custom element.
72123

@@ -76,34 +127,33 @@ on your component would be automatically made available as `greetperson` on your
76127

77128
### Options
78129

79-
| Option | Default | Description |
80-
|------------|:------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
81-
| component | _(required)_ | The constructor for your Svelte component (from `import`) |
82-
| 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)) |
83-
| attributes | `[]` | array - List of attributes to reactively forward to your component (does not reflect changes inside the component). <br> **Important:** Attributes must be the lowercase version of your Svelte component props ([similar to Lit](https://lit.dev/docs/components/properties/#observed-attributes)). |
84-
| shadow | `false` | boolean - Should this component use shadow DOM.<br/> **Note:** Only basic support for shadow DOM is currently provided. See https://github.com/patricknelson/svelte-retag/issues/6. |
85-
| href | `''` | link to your stylesheet - Allows you to ensure your styles are included in the shadow DOM (thus only required when `shadow` is set to `true`). |
86-
| hydratable | `false` | If enabled, allows for SSR/SSG of custom elements managed by `svelte-retag` by including extra markup so that they can be initialized (or "hydrated") client-side from pre-rendered HTML. Enable this during SSR/SSG to allow for proper initialization. See [hydration demo here](https://svelte-retag.vercel.app/hydratable.html). <br><br>Note: Experimental. Compatible with light DOM rendering only. |
130+
| Option | Default | Description |
131+
|--------------|:------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
132+
| `component` | _(required)_ | The constructor for your Svelte component (from `import`) |
133+
| `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)) |
134+
| `attributes` | `[]` | Optional. List of attributes to reactively forward to your component (does not reflect changes inside the component). <br> **Important:** Attributes must be the lowercase version of your Svelte component props ([similar to Lit](https://lit.dev/docs/components/properties/#observed-attributes)). |
135+
| `shadow` | `false` | Optional. Indicates if this component should use shadow DOM.<br/> **Note:** Only basic support for shadow DOM is currently provided. See https://github.com/patricknelson/svelte-retag/issues/6. |
136+
| `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`. |
137+
| `hydratable` | `false` | Optional. If enabled, allows for SSR/SSG of custom elements managed by `svelte-retag` by including extra markup so that they can be initialized (or "hydrated") client-side from pre-rendered HTML. Enable this during SSR/SSG to allow for proper initialization. See [hydration demo here](https://svelte-retag.vercel.app/hydratable.html). <br><br>Note: Experimental. Compatible with light DOM rendering only. |
87138

88139
**Note:** For portability, `svelte-retag`'s API is fully backward compatible
89140
with [`svelte-tag@^1.0.0`](https://github.com/crisward/svelte-tag).
90141

91-
## To Do
92-
93-
On the immediate horizon:
142+
## Change Log
94143

95-
- [x] Migrate to Vitest for unit testing (see https://github.com/crisward/svelte-tag/pull/14)
96-
- [x] Update logo
97-
- [x] Fix nested slot support (https://github.com/patricknelson/svelte-retag/pull/5)
98-
- [x] Better support for slots during early execution of IIFE compiled packages, i.e. use `MutationObserver` to watch
144+
- Migrate to Vitest for unit testing (see https://github.com/crisward/svelte-tag/pull/14)
145+
- Update logo
146+
- Fix nested slot support (https://github.com/patricknelson/svelte-retag/pull/5)
147+
- Better support for slots during early execution of IIFE compiled packages, i.e. use `MutationObserver` to watch
99148
for light DOM slots during initial parsing (see https://github.com/patricknelson/svelte-retag/issues/7)
100-
- [x] Support Lit-style lowercase props (see https://github.com/patricknelson/svelte-retag/pull/9)
101-
- [x] Svelte 4 support (tested)
102-
- [x] Support context (see https://github.com/patricknelson/svelte-retag/issues/10, PR
149+
- Support Lit-style lowercase props (see https://github.com/patricknelson/svelte-retag/pull/9)
150+
- Svelte 4 support (tested)
151+
- Support context (see https://github.com/patricknelson/svelte-retag/issues/10, PR
103152
at https://github.com/patricknelson/svelte-retag/pull/18)
104-
- [x] Add demos (see https://github.com/patricknelson/svelte-retag/issues/11)
153+
- Add demos to vercel site (see https://github.com/patricknelson/svelte-retag/issues/11)
154+
- Add step-by-step instructions and provided a simple MVP example (https://github.com/patricknelson/svelte-retag/pull/24)
105155

106-
Milestones:
156+
### Milestones:
107157

108158
- **v1:** ✅
109159
- **v2:** Utilize Svelte 4's `customElement` syntax, i.e.

‎demo/.gitignore renamed to ‎demo/hello-world/.gitignore

File renamed without changes.

‎demo/.vscode/extensions.json renamed to ‎demo/hello-world/.vscode/extensions.json

File renamed without changes.

‎demo/hello-world/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# svelte-retag: Hello World
2+
3+
This is an **MVP** demo that shows `svelte-retag` in action in its simplest form in local development with a
4+
`HelloWorld.svelte` component implemented as a `<hello-world>` custom element.
5+
6+
To try it out yourself, make sure you have [Git](https://git-scm.com/downloads) and [Node](https://nodejs.org/) installed and then run:
7+
8+
```bash
9+
git clone https://github.com/patricknelson/svelte-retag.git
10+
cd svelte-retag/demo/hello-world
11+
npm install
12+
npm run dev
13+
```
14+
15+
Then open your browser to [http://localhost:5173/](http://localhost:5173/) to view the demo.

‎demo/hello-world/index.html

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="icon" type="image/svg+xml" href="/svelte-retag-favicon.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>svelte-retag: Hello World</title>
8+
</head>
9+
<body>
10+
<hello-world greetperson="👩‍🚀"></hello-world>
11+
<script type="module" src="/src/main.js"></script>
12+
</body>
13+
</html>

‎demo/jsconfig.json renamed to ‎demo/hello-world/jsconfig.json

File renamed without changes.

0 commit comments

Comments
 (0)