docs: Svelte 3/4 differences

note some inline, drive-by-fix in custom element docs closes #8703
sveltejs · Jun 15, 2023 · af580f2 · af580f2
1 parent 62bef80
commit af580f2
Show file tree

Hide file tree

Showing 3 changed files with 15 additions and 2 deletions.
diff --git a/documentation/docs/02-template-syntax/03-logic-blocks.md b/documentation/docs/02-template-syntax/03-logic-blocks.md
@@ -120,7 +120,7 @@ An each block can also have an `{:else}` clause, which is rendered if the list i
 {/each}
 ```
 
-It is possible to iterate over iterables like `Map` or `Set`. Iterables need to be finite and static (they shouldn't change while being iterated over). Under the hood, they are transformed to an array using `Array.from` before being passed off to rendering. If you're writing performance-sensitive code, try to avoid iterables and use regular arrays as they are more performant.
+Since Svelte 4 it is possible to iterate over iterables like `Map` or `Set`. Iterables need to be finite and static (they shouldn't change while being iterated over). Under the hood, they are transformed to an array using `Array.from` before being passed off to rendering. If you're writing performance-sensitive code, try to avoid iterables and use regular arrays as they are more performant.
 
 ## {#await ...}
 

diff --git a/documentation/docs/04-compiler-and-api/01-svelte-compiler.md b/documentation/docs/04-compiler-and-api/01-svelte-compiler.md
@@ -78,6 +78,7 @@ The following options can be passed to the compiler. None are required:
 | `cssOutputFilename`  | `null`                                      | A `string` used for your CSS sourcemap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `sveltePath`         | `"svelte"`                                  | The location of the `svelte` package. Any imports from `svelte` or `svelte/[module]` will be modified accordingly.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `namespace`          | `"html"`                                    | The namespace of the element; e.g., `"mathml"`, `"svg"`, `"foreign"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `format`             | `"esm"`                                     | This option only exists in Svelte 3. If `"esm"`, creates a JavaScript module (with import and export). If `"cjs"`, creates a CommonJS module (with require and module.exports).                                                                                                                                                                                                                                                                                                                                                                                               |
 
 The returned `result` object contains the code for your component, along with useful bits of metadata.
 

diff --git a/documentation/docs/04-compiler-and-api/04-custom-elements-api.md b/documentation/docs/04-compiler-and-api/04-custom-elements-api.md
@@ -5,7 +5,11 @@ title: 'Custom elements API'
 Svelte components can also be compiled to custom elements (aka web components) using the `customElement: true` compiler option. You should specify a tag name for the component using the `<svelte:options>` [element](/docs/special-elements#svelte-options).
 
 ```svelte
+<svelte:options customElement="my-element" />
+
+<!-- in Svelte 3, do this instead:
 <svelte:options tag="my-element" />
+-->
 
 <script>
 	export let name = 'world';
@@ -21,7 +25,9 @@ You can leave out the tag name for any of your inner components which you don't
 // @noErrors
 import MyElement from './MyElement.svelte';
 
-customElements.define('my-element', MyElement);
+customElements.define('my-element', MyElement.element);
+// In Svelte 3, do this instead:
+// customElements.define('my-element', MyElement);
 ```
 
 Once a custom element has been defined, it can be used as a regular DOM element:
@@ -49,6 +55,8 @@ console.log(el.name);
 el.name = 'everybody';
 ```
 
+## Component options
+
 When constructing a custom element, you can tailor several aspects by defining `customElement` as an object within `<svelte:options>`. This object comprises a mandatory `tag` property for the custom element's name, an optional `shadow` property that can be set to `"none"` to forgo shadow root creation (note that styles are then no longer encapsulated, and you can't use slots), and a `props` option, which offers the following settings:
 
 - `attribute: string`: To update a custom element's prop, you have two alternatives: either set the property on the custom element's reference as illustrated above or use an HTML attribute. For the latter, the default attribute name is the lowercase property name. Modify this by assigning `attribute: "<desired name>"`.
@@ -73,6 +81,10 @@ When constructing a custom element, you can tailor several aspects by defining `
 ...
 ```
 
+These options don't exist in Svelte 3.
+
+## Caveats and limitations
+
 Custom elements can be a useful way to package components for consumption in a non-Svelte app, as they will work with vanilla HTML and JavaScript as well as [most frameworks](https://custom-elements-everywhere.com/). There are, however, some important differences to be aware of:
 
 - Styles are _encapsulated_, rather than merely _scoped_ (unless you set `shadow: "none"`). This means that any non-component styles (such as you might have in a `global.css` file) will not apply to the custom element, including styles with the `:global(...)` modifier
-Original file line number
+Diff line change
@@ Expand Up @@
     {/each}
     ```
-    It is possible to iterate over iterables like `Map` or `Set`. Iterables need to be finite and static (they shouldn't change while being iterated over). Under the hood, they are transformed to an array using `Array.from` before being passed off to rendering. If you're writing performance-sensitive code, try to avoid iterables and use regular arrays as they are more performant.
+    Since Svelte 4 it is possible to iterate over iterables like `Map` or `Set`. Iterables need to be finite and static (they shouldn't change while being iterated over). Under the hood, they are transformed to an array using `Array.from` before being passed off to rendering. If you're writing performance-sensitive code, try to avoid iterables and use regular arrays as they are more performant.
     ## {#await ...}
@@ Expand Down @@