From 44e66fa0b61099815092cd80420897e9dce94650 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Tue, 22 Oct 2024 01:20:54 -0400 Subject: [PATCH 1/3] sync --- .../20-creating-a-project.md | 4 +- .../30-project-structure.md | 6 +- .../kit/20-core-concepts/30-form-actions.md | 2 +- .../25-build-and-deploy/30-adapter-auto.md | 2 +- .../docs/kit/30-advanced/70-packaging.md | 6 +- .../docs/kit/60-appendix/20-integrations.md | 16 +- .../30-migrating-to-sveltekit-2.md | 2 +- .../svelte/01-introduction/03-svelte-files.md | 3 + .../01-introduction/04-svelte-js-files.md | 3 + .../docs/svelte/02-runes/01-what-are-runes.md | 3 + .../03-template-syntax/01-basic-markup.md | 4 +- .../docs/svelte/03-template-syntax/10-bind.md | 6 +- .../docs/svelte/03-template-syntax/11-use.md | 114 +++---- .../03-template-syntax/12-transition.md | 302 ++---------------- .../03-template-syntax/13-in-and-out.md | 8 +- .../svelte/03-template-syntax/14-animate.md | 115 ++++++- .../03-template-syntax/15-class-and-style.md | 5 - .../svelte/03-template-syntax/15-class.md | 23 ++ .../svelte/03-template-syntax/16-style.md | 41 +++ .../svelte/04-styling/01-scoped-styles.md | 42 +++ .../04-styling/01-styles-and-classes.md | 235 -------------- .../svelte/04-styling/02-global-styles.md | 65 ++++ .../svelte/04-styling/03-custom-properties.md | 57 ++++ .../04-styling/04-nested-style-elements.md | 21 ++ .../05-special-elements/01-svelte-window.md | 44 +++ .../05-special-elements/02-svelte-document.md | 28 ++ .../05-special-elements/03-svelte-body.md | 15 + .../05-special-elements/04-svelte-head.md | 18 ++ .../05-special-elements/05-svelte-element.md | 31 ++ .../05-special-elements/06-svelte-options.md | 22 ++ .../09-special-elements.md | 190 ----------- .../docs/svelte/06-runtime/01-stores.md | 4 +- .../docs/svelte/06-runtime/02-context.md | 4 +- .../svelte/06-runtime/03-lifecycle-hooks.md | 4 +- .../06-runtime/04-imperative-component-api.md | 4 +- .../docs/svelte/07-misc/04-custom-elements.md | 2 +- .../.generated/client-warnings.md | 2 +- .../svelte/99-legacy/00-legacy-overview.md | 12 + .../docs/svelte/99-legacy/01-legacy-let.md | 34 ++ .../02-legacy-reactive-assignments.md | 87 +++++ .../svelte/99-legacy/03-legacy-export-let.md | 72 +++++ .../04-legacy-$$props-and-$$restProps.md | 30 ++ .../docs/svelte/99-legacy/10-legacy-on.md | 136 ++++++++ .../docs/svelte/99-legacy/20-legacy-slots.md | 116 +++++++ .../svelte/99-legacy/21-legacy-$$slots.md | 27 ++ .../99-legacy/22-legacy-svelte-fragment.md | 32 ++ .../99-legacy/30-legacy-svelte-component.md | 13 + .../svelte/99-legacy/31-legacy-svelte-self.md | 37 +++ .../99-legacy/40-legacy-component-api.md | 200 ++++++++++++ .../content/docs/svelte/99-legacy/index.md | 3 + 50 files changed, 1452 insertions(+), 800 deletions(-) delete mode 100644 apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class-and-style.md create mode 100644 apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class.md create mode 100644 apps/svelte.dev/content/docs/svelte/03-template-syntax/16-style.md create mode 100644 apps/svelte.dev/content/docs/svelte/04-styling/01-scoped-styles.md delete mode 100644 apps/svelte.dev/content/docs/svelte/04-styling/01-styles-and-classes.md create mode 100644 apps/svelte.dev/content/docs/svelte/04-styling/02-global-styles.md create mode 100644 apps/svelte.dev/content/docs/svelte/04-styling/03-custom-properties.md create mode 100644 apps/svelte.dev/content/docs/svelte/04-styling/04-nested-style-elements.md create mode 100644 apps/svelte.dev/content/docs/svelte/05-special-elements/01-svelte-window.md create mode 100644 apps/svelte.dev/content/docs/svelte/05-special-elements/02-svelte-document.md create mode 100644 apps/svelte.dev/content/docs/svelte/05-special-elements/03-svelte-body.md create mode 100644 apps/svelte.dev/content/docs/svelte/05-special-elements/04-svelte-head.md create mode 100644 apps/svelte.dev/content/docs/svelte/05-special-elements/05-svelte-element.md create mode 100644 apps/svelte.dev/content/docs/svelte/05-special-elements/06-svelte-options.md delete mode 100644 apps/svelte.dev/content/docs/svelte/05-special-elements/09-special-elements.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/00-legacy-overview.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/01-legacy-let.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/02-legacy-reactive-assignments.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/03-legacy-export-let.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/04-legacy-$$props-and-$$restProps.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/10-legacy-on.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/20-legacy-slots.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/21-legacy-$$slots.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/30-legacy-svelte-component.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/31-legacy-svelte-self.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/40-legacy-component-api.md create mode 100644 apps/svelte.dev/content/docs/svelte/99-legacy/index.md diff --git a/apps/svelte.dev/content/docs/kit/10-getting-started/20-creating-a-project.md b/apps/svelte.dev/content/docs/kit/10-getting-started/20-creating-a-project.md index cca9caf3e4..d86d1e3d1a 100644 --- a/apps/svelte.dev/content/docs/kit/10-getting-started/20-creating-a-project.md +++ b/apps/svelte.dev/content/docs/kit/10-getting-started/20-creating-a-project.md @@ -2,10 +2,10 @@ title: Creating a project --- -The easiest way to start building a SvelteKit app is to run `npm create`: +The easiest way to start building a SvelteKit app is to run `npx sv create`: ```bash -npm create svelte@latest my-app +npx sv create my-app cd my-app npm install npm run dev diff --git a/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md b/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md index 5b7ac9a3cc..34b938c0a8 100644 --- a/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md +++ b/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md @@ -30,7 +30,7 @@ my-project/ └ vite.config.js ``` -You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc` and `eslint.config.js` and so on, if you chose those options when running `npm create svelte@latest`). +You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc` and `eslint.config.js` and so on, if you chose those options when running `npx sv create`). ## Project files @@ -71,7 +71,7 @@ If you added [Playwright](https://playwright.dev/) for browser testing when you Your `package.json` file must include `@sveltejs/kit`, `svelte` and `vite` as `devDependencies`. -When you create a project with `npm create svelte@latest`, you'll also notice that `package.json` includes `"type": "module"`. This means that `.js` files are interpreted as native JavaScript modules with `import` and `export` keywords. Legacy CommonJS files need a `.cjs` file extension. +When you create a project with `npx sv create`, you'll also notice that `package.json` includes `"type": "module"`. This means that `.js` files are interpreted as native JavaScript modules with `import` and `export` keywords. Legacy CommonJS files need a `.cjs` file extension. ### svelte.config.js @@ -79,7 +79,7 @@ This file contains your Svelte and SvelteKit [configuration](configuration). ### tsconfig.json -This file (or `jsconfig.json`, if you prefer type-checked `.js` files over `.ts` files) configures TypeScript, if you added typechecking during `npm create svelte@latest`. Since SvelteKit relies on certain configuration being set a specific way, it generates its own `.svelte-kit/tsconfig.json` file which your own config `extends`. +This file (or `jsconfig.json`, if you prefer type-checked `.js` files over `.ts` files) configures TypeScript, if you added typechecking during `npx sv create`. Since SvelteKit relies on certain configuration being set a specific way, it generates its own `.svelte-kit/tsconfig.json` file which your own config `extends`. ### vite.config.js diff --git a/apps/svelte.dev/content/docs/kit/20-core-concepts/30-form-actions.md b/apps/svelte.dev/content/docs/kit/20-core-concepts/30-form-actions.md index cad63a3df3..57ea567f21 100644 --- a/apps/svelte.dev/content/docs/kit/20-core-concepts/30-form-actions.md +++ b/apps/svelte.dev/content/docs/kit/20-core-concepts/30-form-actions.md @@ -346,7 +346,7 @@ The easiest way to progressively enhance a form is to add the `use:enhance` acti
``` -> `use:enhance` can only be used with forms that have `method="POST"`. It will not work with `method="GET"`, which is the default for forms without a specified method. Attempting to use `use:enhance` on forms without `method="POST"` will result in an error. +> [!NOTE] `use:enhance` can only be used with forms that have `method="POST"`. It will not work with `method="GET"`, which is the default for forms without a specified method. Attempting to use `use:enhance` on forms without `method="POST"` will result in an error. > [!NOTE] Yes, it's a little confusing that the `enhance` action and `` are both called 'action'. These docs are action-packed. Sorry. diff --git a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/30-adapter-auto.md b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/30-adapter-auto.md index e699866aeb..a1c682168c 100644 --- a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/30-adapter-auto.md +++ b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/30-adapter-auto.md @@ -2,7 +2,7 @@ title: Zero-config deployments --- -When you create a new SvelteKit project with `npm create svelte@latest`, it installs [`adapter-auto`](https://github.com/sveltejs/kit/tree/main/packages/adapter-auto) by default. This adapter automatically installs and uses the correct adapter for supported environments when you deploy: +When you create a new SvelteKit project with `npx sv create`, it installs [`adapter-auto`](https://github.com/sveltejs/kit/tree/main/packages/adapter-auto) by default. This adapter automatically installs and uses the correct adapter for supported environments when you deploy: - [`@sveltejs/adapter-cloudflare`](adapter-cloudflare) for [Cloudflare Pages](https://developers.cloudflare.com/pages/) - [`@sveltejs/adapter-netlify`](adapter-netlify) for [Netlify](https://netlify.com/) diff --git a/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md b/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md index e2c67b2586..e0c17a311b 100644 --- a/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md +++ b/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md @@ -2,7 +2,7 @@ title: Packaging --- -You can use SvelteKit to build apps as well as component libraries, using the `@sveltejs/package` package (`npm create svelte` has an option to set this up for you). +You can use SvelteKit to build apps as well as component libraries, using the `@sveltejs/package` package (`npx sv create` has an option to set this up for you). When you're creating an app, the contents of `src/routes` is the public-facing stuff; [`src/lib`]($lib) contains your app's internal library. @@ -59,7 +59,7 @@ Read more about it [here](https://docs.npmjs.com/cli/v9/configuring-npm/package- ### exports -The `"exports"` field contains the package's entry points. If you set up a new library project through `npm create svelte@latest`, it's set to a single export, the package root: +The `"exports"` field contains the package's entry points. If you set up a new library project through `npx sv create`, it's set to a single export, the package root: ```json { @@ -157,7 +157,7 @@ This will treat only the specified files as having side effects. ## TypeScript -You should ship type definitions for your library even if you don't use TypeScript yourself so that people who do get proper intellisense when using your library. `@sveltejs/package` makes the process of generating types mostly opaque to you. By default, when packaging your library, type definitions are auto-generated for JavaScript, TypeScript and Svelte files. All you need to ensure is that the `types` condition in the [exports](#Anatomy-of-a-package.json-exports) map points to the correct files. When initialising a library project through `npm create svelte@latest`, this is automatically setup for the root export. +You should ship type definitions for your library even if you don't use TypeScript yourself so that people who do get proper intellisense when using your library. `@sveltejs/package` makes the process of generating types mostly opaque to you. By default, when packaging your library, type definitions are auto-generated for JavaScript, TypeScript and Svelte files. All you need to ensure is that the `types` condition in the [exports](#Anatomy-of-a-package.json-exports) map points to the correct files. When initialising a library project through `npx sv create`, this is automatically setup for the root export. If you have something else than a root export however — for example providing a `your-library/foo` import — you need to take additional care for providing type definitions. Unfortunately, TypeScript by default will _not_ resolve the `types` condition for an export like `{ "./foo": { "types": "./dist/foo.d.ts", ... }}`. Instead, it will search for a `foo.d.ts` relative to the root of your library (i.e. `your-library/foo.d.ts` instead of `your-library/dist/foo.d.ts`). To fix this, you have two options: diff --git a/apps/svelte.dev/content/docs/kit/60-appendix/20-integrations.md b/apps/svelte.dev/content/docs/kit/60-appendix/20-integrations.md index 6a6b5f03ca..d3d9a8fcf7 100644 --- a/apps/svelte.dev/content/docs/kit/60-appendix/20-integrations.md +++ b/apps/svelte.dev/content/docs/kit/60-appendix/20-integrations.md @@ -17,11 +17,17 @@ export default { ## Adders -Run `npx svelte-add` to setup many different complex integrations with a single command including: -- CSS - Tailwind, Bootstrap, Bulma -- database - Drizzle ORM -- markdown - mdsvex -- Storybook +Run `npx sv add` to setup many different complex integrations with a single command including: +- prettier (formatting) +- eslint (linting) +- vitest (unit testing) +- playwright (e2e testing) +- lucia (auth) +- tailwind (CSS) +- drizzle (DB) +- paraglide (i18n) +- mdsvex (markdown) +- storybook (frontend workshop) ## Directory diff --git a/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md b/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md index e7f9147372..148d8b08b6 100644 --- a/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md +++ b/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md @@ -2,7 +2,7 @@ title: Migrating to SvelteKit v2 --- -Upgrading from SvelteKit version 1 to version 2 should be mostly seamless. There are a few breaking changes to note, which are listed here. You can use `npx svelte-migrate@latest sveltekit-2` to migrate some of these changes automatically. +Upgrading from SvelteKit version 1 to version 2 should be mostly seamless. There are a few breaking changes to note, which are listed here. You can use `npx sv migrate sveltekit-2` to migrate some of these changes automatically. We highly recommend upgrading to the most recent 1.x version before upgrading to 2.0, so that you can take advantage of targeted deprecation warnings. We also recommend [updating to Svelte 4](https://svelte.dev/docs/v4-migration-guide) first: Later versions of SvelteKit 1.x support it, and SvelteKit 2.0 requires it. diff --git a/apps/svelte.dev/content/docs/svelte/01-introduction/03-svelte-files.md b/apps/svelte.dev/content/docs/svelte/01-introduction/03-svelte-files.md index f534e30fcb..e3dd72c222 100644 --- a/apps/svelte.dev/content/docs/svelte/01-introduction/03-svelte-files.md +++ b/apps/svelte.dev/content/docs/svelte/01-introduction/03-svelte-files.md @@ -50,6 +50,9 @@ A ` -
+
...
``` -An action can have a parameter. If the returned value has an `update` method, it will be called immediately after Svelte has applied updates to the markup whenever that parameter changes. - -> [!NOTE] Don't worry that we're redeclaring the `foo` function for every component instance — Svelte will hoist any functions that don't depend on local state out of the component definition. +An action can be called with an argument: ```svelte -
+
...
``` -## Attributes +The action is only called once (but not during server-side rendering) — it will _not_ run again if the argument changes. + +> [!LEGACY] +> Prior to the `$effect` rune, actions could return an object with `update` and `destroy` methods, where `update` would be called with the latest value of the argument if it changed. Using effects is preferred. -Sometimes actions emit custom events and apply custom attributes to the element they are applied to. To support this, actions typed with `Action` or `ActionReturn` type can have a last parameter, `Attributes`: +## Typing + +The `Action` interface receives three optional type arguments — a node type (which can be `Element`, if the action applies to everything), a parameter, and any custom event handlers created by the action.: ```svelte -
+
...
``` diff --git a/apps/svelte.dev/content/docs/svelte/03-template-syntax/12-transition.md b/apps/svelte.dev/content/docs/svelte/03-template-syntax/12-transition.md index 114d4d9780..51f1008209 100644 --- a/apps/svelte.dev/content/docs/svelte/03-template-syntax/12-transition.md +++ b/apps/svelte.dev/content/docs/svelte/03-template-syntax/12-transition.md @@ -2,70 +2,31 @@ title: transition: --- -- how to use (template syntax) -- when to use -- global vs local -- easing & motion -- mention imports -- key block +A _transition_ is triggered by an element entering or leaving the DOM as a result of a state change. -Svelte provides different techniques and syntax for incorporating motion into your Svelte projects. +When a block (such as an `{#if ...}` block) is transitioning out, all elements inside it, including those that do not have their own transitions, are kept in the DOM until every transition in the block has been completed. -## transition:_fn_ - -```svelte - -transition:fn -``` - -```svelte - -transition:fn={params} -``` - -```svelte - -transition:fn|global -``` +The `transition:` directive indicates a _bidirectional_ transition, which means it can be smoothly reversed while the transition is in progress. ```svelte - -transition:fn|global={params} -``` + -```svelte - -transition:fn|local={params} -``` + -```js -/// copy: false -// @noErrors -transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => { - delay?: number, - duration?: number, - easing?: (t: number) => number, - css?: (t: number, u: number) => string, - tick?: (t: number, u: number) => void -} +{#if visible} +
fades in and out
+{/if} ``` -A transition is triggered by an element entering or leaving the DOM as a result of a state change. +## Built-in transitions -When a block is transitioning out, all elements inside the block, including those that do not have their own transitions, are kept in the DOM until every transition in the block has been completed. +A selection of built-in transitions can be imported from the [`svelte/transition`](svelte-transition) module. -The `transition:` directive indicates a _bidirectional_ transition, which means it can be smoothly reversed while the transition is in progress. - -```svelte -{#if visible} -
fades in and out
-{/if} -``` +## Local vs global Transitions are local by default. Local transitions only play when the block they belong to is created or destroyed, _not_ when parent blocks are created or destroyed. @@ -79,8 +40,6 @@ Transitions are local by default. Local transitions only play when the block the {/if} ``` -> [!NOTE] By default intro transitions will not play on first render. You can modify this behaviour by setting `intro: true` when you [create a component](imperative-component-api) and marking the transition as `global`. - ## Transition parameters Transitions can have parameters. @@ -95,7 +54,19 @@ Transitions can have parameters. ## Custom transition functions -Transitions can use custom functions. If the returned object has a `css` function, Svelte will create a CSS animation that plays on the element. +```js +/// copy: false +// @noErrors +transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => { + delay?: number, + duration?: number, + easing?: (t: number) => number, + css?: (t: number, u: number) => string, + tick?: (t: number, u: number) => void +} +``` + +Transitions can use custom functions. If the returned object has a `css` function, Svelte will generate keyframes for a [web animation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API). The `t` argument passed to `css` is a value between `0` and `1` after the `easing` function has been applied. _In_ transitions run from `0` to `1`, _out_ transitions run from `1` to `0` — in other words, `1` is the element's natural state, as though no transition had been applied. The `u` argument is equal to `1 - t`. @@ -132,7 +103,7 @@ The function is called repeatedly _before_ the transition begins, with different A custom transition function can also return a `tick` function, which is called _during_ the transition with the same `t` and `u` arguments. -> [!NOTE] If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices. +> [!NOTE] If it's possible to use `css` instead of `tick`, do so — web animations can run off the main thread, preventing jank on slower devices. ```svelte @@ -189,222 +160,13 @@ An element with transitions will dispatch the following events in addition to an {#if visible}

(status = 'intro started')} - on:outrostart={() => (status = 'outro started')} - on:introend={() => (status = 'intro ended')} - on:outroend={() => (status = 'outro ended')} + onintrostart={() => (status = 'intro started')} + onoutrostart={() => (status = 'outro started')} + onintroend={() => (status = 'intro ended')} + onoutroend={() => (status = 'outro ended')} > Flies in and out

{/if} ``` -## in:_fn_/out:_fn_ - -```svelte - -in:fn -``` - -```svelte - -in:fn={params} -``` - -```svelte - -in:fn|global -``` - -```svelte - -in:fn|global={params} -``` - -```svelte - -in:fn|local -``` - -```svelte - -in:fn|local={params} -``` - -```svelte - -out:fn -``` - -```svelte - -out:fn={params} -``` - -```svelte - -out:fn|global -``` - -```svelte - -out:fn|global={params} -``` - -```svelte - -out:fn|local -``` - -```svelte - -out:fn|local={params} -``` - -Similar to `transition:`, but only applies to elements entering (`in:`) or leaving (`out:`) the DOM. - -Unlike with `transition:`, transitions applied with `in:` and `out:` are not bidirectional — an in transition will continue to 'play' alongside the out transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch. - -```svelte -{#if visible} -
flies in, fades out
-{/if} -``` - -## animate:_fn_ - -```svelte - -animate:name -``` - -```svelte - -animate:name={params} -``` - -```js -/// copy: false -// @noErrors -animation = (node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => { - delay?: number, - duration?: number, - easing?: (t: number) => number, - css?: (t: number, u: number) => string, - tick?: (t: number, u: number) => void -} -``` - -```ts -/// copy: false -// @noErrors -DOMRect { - bottom: number, - height: number, - ​​left: number, - right: number, - ​top: number, - width: number, - x: number, - y: number -} -``` - -An animation is triggered when the contents of a [keyed each block](each) are re-ordered. Animations do not run when an element is added or removed, only when the index of an existing data item within the each block changes. Animate directives must be on an element that is an _immediate_ child of a keyed each block. - -Animations can be used with Svelte's [built-in animation functions](svelte-animate) or [custom animation functions](#Custom-animation-functions). - -```svelte - -{#each list as item, index (item)} -
  • {item}
    • -{/each} -``` - -## Animation Parameters - -As with actions and transitions, animations can have parameters. - -(The double `{{curlies}}` aren't a special syntax; this is an object literal inside an expression tag.) - -```svelte -{#each list as item, index (item)} -
  • {item}
    • -{/each} -``` - -## Custom animation functions - -Animations can use custom functions that provide the `node`, an `animation` object and any `parameters` as arguments. The `animation` parameter is an object containing `from` and `to` properties each containing a [DOMRect](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect#Properties) describing the geometry of the element in its `start` and `end` positions. The `from` property is the DOMRect of the element in its starting position, and the `to` property is the DOMRect of the element in its final position after the list has been reordered and the DOM updated. - -If the returned object has a `css` method, Svelte will create a CSS animation that plays on the element. - -The `t` argument passed to `css` is a value that goes from `0` and `1` after the `easing` function has been applied. The `u` argument is equal to `1 - t`. - -The function is called repeatedly _before_ the animation begins, with different `t` and `u` arguments. - - - -```svelte - - - -{#each list as item, index (item)} -
    {item}
    -{/each} -``` - -A custom animation function can also return a `tick` function, which is called _during_ the animation with the same `t` and `u` arguments. - -> [!NOTE] If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices. - -```svelte - - - -{#each list as item, index (item)} -
    {item}
    -{/each} -``` diff --git a/apps/svelte.dev/content/docs/svelte/03-template-syntax/13-in-and-out.md b/apps/svelte.dev/content/docs/svelte/03-template-syntax/13-in-and-out.md index a6e9338f82..feb5aa84c5 100644 --- a/apps/svelte.dev/content/docs/svelte/03-template-syntax/13-in-and-out.md +++ b/apps/svelte.dev/content/docs/svelte/03-template-syntax/13-in-and-out.md @@ -2,4 +2,10 @@ title: in: and out: --- -Coming soon! +The `in:` and `out:` directives are identical to [`transition:`](transition), except that the resulting transitions are not bidirectional — an `in` transition will continue to 'play' alongside the `out` transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch. + +```svelte +{#if visible} +
    flies in, fades out
    +{/if} +``` diff --git a/apps/svelte.dev/content/docs/svelte/03-template-syntax/14-animate.md b/apps/svelte.dev/content/docs/svelte/03-template-syntax/14-animate.md index 03af0ec821..583936be3b 100644 --- a/apps/svelte.dev/content/docs/svelte/03-template-syntax/14-animate.md +++ b/apps/svelte.dev/content/docs/svelte/03-template-syntax/14-animate.md @@ -2,4 +2,117 @@ title: animate: --- -Coming soon! + + + +An animation is triggered when the contents of a [keyed each block](each#Keyed-each-blocks) are re-ordered. Animations do not run when an element is added or removed, only when the index of an existing data item within the each block changes. Animate directives must be on an element that is an _immediate_ child of a keyed each block. + +Animations can be used with Svelte's [built-in animation functions](svelte-animate) or [custom animation functions](#Custom-animation-functions). + +```svelte + +{#each list as item, index (item)} +
  • {item}
    • +{/each} +``` + +## Animation Parameters + +As with actions and transitions, animations can have parameters. + +(The double `{{curlies}}` aren't a special syntax; this is an object literal inside an expression tag.) + +```svelte +{#each list as item, index (item)} +
  • {item}
    • +{/each} +``` + +## Custom animation functions + +```js +/// copy: false +// @noErrors +animation = (node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => { + delay?: number, + duration?: number, + easing?: (t: number) => number, + css?: (t: number, u: number) => string, + tick?: (t: number, u: number) => void +} +``` + +Animations can use custom functions that provide the `node`, an `animation` object and any `parameters` as arguments. The `animation` parameter is an object containing `from` and `to` properties each containing a [DOMRect](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect#Properties) describing the geometry of the element in its `start` and `end` positions. The `from` property is the DOMRect of the element in its starting position, and the `to` property is the DOMRect of the element in its final position after the list has been reordered and the DOM updated. + +If the returned object has a `css` method, Svelte will create a [web animation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) that plays on the element. + +The `t` argument passed to `css` is a value that goes from `0` and `1` after the `easing` function has been applied. The `u` argument is equal to `1 - t`. + +The function is called repeatedly _before_ the animation begins, with different `t` and `u` arguments. + + + +```svelte + + + +{#each list as item, index (item)} +
    {item}
    +{/each} +``` + +A custom animation function can also return a `tick` function, which is called _during_ the animation with the same `t` and `u` arguments. + +> [!NOTE] If it's possible to use `css` instead of `tick`, do so — web animations can run off the main thread, preventing jank on slower devices. + +```svelte + + + +{#each list as item, index (item)} +
    {item}
    +{/each} +``` + diff --git a/apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class-and-style.md b/apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class-and-style.md deleted file mode 100644 index 755c47addb..0000000000 --- a/apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class-and-style.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: class: and style: ---- - -Coming soon! diff --git a/apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class.md b/apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class.md new file mode 100644 index 0000000000..cecbc7cf20 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/03-template-syntax/15-class.md @@ -0,0 +1,23 @@ +--- +title: class: +--- + +The `class:` directive is a convenient way to conditionally set classes on elements, as an alternative to using conditional expressions inside `class` attributes: + +```svelte + +
    ...
    +
    ...
    +``` + +As with other directives, we can use a shorthand when the name of the class coincides with the value: + +```svelte +
    ...
    +``` + +Multiple `class:` directives can be added to a single element: + +```svelte +
    ...
    +``` diff --git a/apps/svelte.dev/content/docs/svelte/03-template-syntax/16-style.md b/apps/svelte.dev/content/docs/svelte/03-template-syntax/16-style.md new file mode 100644 index 0000000000..749376c6e2 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/03-template-syntax/16-style.md @@ -0,0 +1,41 @@ +--- +title: style: +--- + +The `style:` directive provides a shorthand for setting multiple styles on an element. + +```svelte + +
    ...
    +
    ...
    +``` + +The value can contain arbitrary expressions: + +```svelte +
    ...
    +``` + +The shorthand form is allowed: + +```svelte +
    ...
    +``` + +Multiple styles can be set on a single element: + +```svelte +
    ...
    +``` + +To mark a style as important, use the `|important` modifier: + +```svelte +
    ...
    +``` + +When `style:` directives are combined with `style` attributes, the directives will take precedence: + +```svelte +
    This will be red
    +``` diff --git a/apps/svelte.dev/content/docs/svelte/04-styling/01-scoped-styles.md b/apps/svelte.dev/content/docs/svelte/04-styling/01-scoped-styles.md new file mode 100644 index 0000000000..f870d0a5b8 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/04-styling/01-scoped-styles.md @@ -0,0 +1,42 @@ +--- +title: Scoped styles +--- + +Svelte components can include a ` +``` + +## Specificity + +Each scoped selector receives a [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) increase of 0-1-0, as a result of the scoping class (e.g. `.svelte-123xyz`) being added to the selector. This means that (for example) a `p` selector defined in a component will take precedence over a `p` selector defined in a global stylesheet, even if the global stylesheet is loaded later. + +In some cases, the scoping class must be added to a selector multiple times, but after the first occurrence it is added with `:where(.svelte-xyz123)` in order to not increase specificity further. + +## Scoped keyframes + +If a component defines `@keyframes`, the name is scoped to the component using the same hashing approach. Any `animation` rules in the component will be similarly adjusted: + +```svelte + +``` + + + diff --git a/apps/svelte.dev/content/docs/svelte/04-styling/01-styles-and-classes.md b/apps/svelte.dev/content/docs/svelte/04-styling/01-styles-and-classes.md deleted file mode 100644 index 8bc99b658e..0000000000 --- a/apps/svelte.dev/content/docs/svelte/04-styling/01-styles-and-classes.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: Styles & Classes ---- - -- style scoping -- `:global` -- `style:` -- `class:` -- `--css` props - -Styling is a fundamental part of UI components. Svelte helps you style your components with ease, providing useful features out of the box. - -## Scoped by default - -By default CSS inside a ` -``` - -## :global(...) - -To apply styles to a single selector globally, use the `:global(...)` modifier: - -```svelte - -``` - -If you want to make @keyframes that are accessible globally, you need to prepend your keyframe names with `-global-`. - -The `-global-` part will be removed when compiled, and the keyframe will then be referenced using just `my-animation-name` elsewhere in your code. - -```svelte - -``` - -## :global - -To apply styles to a group of selectors globally, create a `:global {...}` block: - -```svelte - -``` - -> [!NOTE] The second example above could also be written as an equivalent `.a :global .b .c .d` selector, where everything after the `:global` is unscoped, though the nested form is preferred. - -## Nested style tags - -There should only be 1 top-level ` -
    -``` - -## class:_name_ - -```svelte - -class:name={value} -``` - -```svelte - -class:name -``` - -A `class:` directive provides a shorter way of toggling a class on an element. - -```svelte - -
    ...
    -
    ...
    - - -
    ...
    - - -
    ...
    -``` - -## style:_property_ - -```svelte - -style:property={value} -``` - -```svelte - -style:property="value" -``` - -```svelte - -style:property -``` - -The `style:` directive provides a shorthand for setting multiple styles on an element. - -```svelte - -
    ...
    -
    ...
    - - -
    ...
    - - -
    ...
    - - -
    ...
    - - -
    ...
    -``` - -When `style:` directives are combined with `style` attributes, the directives will take precedence: - -```svelte -
    This will be red
    -``` - -## --style-props - -```svelte - ---style-props="anycssvalue" -``` - -You can also pass styles as props to components for the purposes of theming, using CSS custom properties. - -Svelte's implementation is essentially syntactic sugar for adding a wrapper element. This example: - -```svelte - -``` - -Desugars to this: - -```svelte - - - -``` - -For SVG namespace, the example above desugars into using `` instead: - -```svelte - - - -``` - -> [!NOTE] Since this is an extra `` (or ``), beware that your CSS structure might accidentally target this. Be mindful of this added wrapper element when using this feature. - -Svelte's CSS Variables support allows for easily themeable components: - -```svelte - -``` - -So you can set a high-level theme color: - -```css -/* global.css */ -html { - --theme-color: black; -} -``` - -Or override it at the consumer level: - -```svelte - -``` diff --git a/apps/svelte.dev/content/docs/svelte/04-styling/02-global-styles.md b/apps/svelte.dev/content/docs/svelte/04-styling/02-global-styles.md new file mode 100644 index 0000000000..8e9cf8d0cb --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/04-styling/02-global-styles.md @@ -0,0 +1,65 @@ +--- +title: Global styles +--- + +## :global(...) + +To apply styles to a single selector globally, use the `:global(...)` modifier: + +```svelte + +``` + +If you want to make @keyframes that are accessible globally, you need to prepend your keyframe names with `-global-`. + +The `-global-` part will be removed when compiled, and the keyframe will then be referenced using just `my-animation-name` elsewhere in your code. + +```svelte + +``` + +## :global + +To apply styles to a group of selectors globally, create a `:global {...}` block: + +```svelte + +``` + +> [!NOTE] The second example above could also be written as an equivalent `.a :global .b .c .d` selector, where everything after the `:global` is unscoped, though the nested form is preferred. diff --git a/apps/svelte.dev/content/docs/svelte/04-styling/03-custom-properties.md b/apps/svelte.dev/content/docs/svelte/04-styling/03-custom-properties.md new file mode 100644 index 0000000000..49984c6ce4 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/04-styling/03-custom-properties.md @@ -0,0 +1,57 @@ +--- +title: Custom properties +--- + +You can pass CSS custom properties — both static and dynamic — to components: + +```svelte + +``` + +The above code essentially desugars to this: + +```svelte + + + +``` + +For an SVG element, it would use `` instead: + +```svelte + + + +``` + +Inside the component, we can read these custom properties (and provide fallback values) using [`var(...)`](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties): + +```svelte + +``` + +You don't _have_ to specify the values directly on the component; as long as the custom properties are defined on a parent element, the component can use them. It's common to define custom properties on the `:root` element in a global stylesheet so that they apply to your entire application. + +> [!NOTE] While the extra element will not affect layout, it _will_ affect any CSS selectors that (for example) use the `>` combinator to target an element directly inside the component's container. diff --git a/apps/svelte.dev/content/docs/svelte/04-styling/04-nested-style-elements.md b/apps/svelte.dev/content/docs/svelte/04-styling/04-nested-style-elements.md new file mode 100644 index 0000000000..6198c636d5 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/04-styling/04-nested-style-elements.md @@ -0,0 +1,21 @@ +--- +title: Nested +
    +``` diff --git a/apps/svelte.dev/content/docs/svelte/05-special-elements/01-svelte-window.md b/apps/svelte.dev/content/docs/svelte/05-special-elements/01-svelte-window.md new file mode 100644 index 0000000000..d4aab36f3b --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-special-elements/01-svelte-window.md @@ -0,0 +1,44 @@ +--- +title: +--- + +```svelte + +``` + +```svelte + +``` + +The `` element allows you to add event listeners to the `window` object without worrying about removing them when the component is destroyed, or checking for the existence of `window` when server-side rendering. + +This element may only appear at the top level of your component — it cannot be inside a block or element. + +```svelte + + + +``` + +You can also bind to the following properties: + +- `innerWidth` +- `innerHeight` +- `outerWidth` +- `outerHeight` +- `scrollX` +- `scrollY` +- `online` — an alias for `window.navigator.onLine` +- `devicePixelRatio` + +All except `scrollX` and `scrollY` are readonly. + +```svelte + +``` + +> [!NOTE] Note that the page will not be scrolled to the initial value to avoid accessibility issues. Only subsequent changes to the bound variable of `scrollX` and `scrollY` will cause scrolling. If you have a legitimate reason to scroll when the component is rendered, call `scrollTo()` in an `$effect`. diff --git a/apps/svelte.dev/content/docs/svelte/05-special-elements/02-svelte-document.md b/apps/svelte.dev/content/docs/svelte/05-special-elements/02-svelte-document.md new file mode 100644 index 0000000000..43f02865e6 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-special-elements/02-svelte-document.md @@ -0,0 +1,28 @@ +--- +title: +--- + +```svelte + +``` + +```svelte + +``` + +Similarly to ``, this element allows you to add listeners to events on `document`, such as `visibilitychange`, which don't fire on `window`. It also lets you use [actions](use) on `document`. + +As with ``, this element may only appear the top level of your component and must never be inside a block or element. + +```svelte + +``` + +You can also bind to the following properties: + +- `activeElement` +- `fullscreenElement` +- `pointerLockElement` +- `visibilityState` + +All are readonly. diff --git a/apps/svelte.dev/content/docs/svelte/05-special-elements/03-svelte-body.md b/apps/svelte.dev/content/docs/svelte/05-special-elements/03-svelte-body.md new file mode 100644 index 0000000000..d6536b0b74 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-special-elements/03-svelte-body.md @@ -0,0 +1,15 @@ +--- +title: +--- + +```svelte + +``` + +Similarly to ``, this element allows you to add listeners to events on `document.body`, such as `mouseenter` and `mouseleave`, which don't fire on `window`. It also lets you use [actions](use) on the `` element. + +As with `` and ``, this element may only appear the top level of your component and must never be inside a block or element. + +```svelte + +``` diff --git a/apps/svelte.dev/content/docs/svelte/05-special-elements/04-svelte-head.md b/apps/svelte.dev/content/docs/svelte/05-special-elements/04-svelte-head.md new file mode 100644 index 0000000000..f7cd7ca20a --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-special-elements/04-svelte-head.md @@ -0,0 +1,18 @@ +--- +title: +--- + +```svelte +... +``` + +This element makes it possible to insert elements into `document.head`. During server-side rendering, `head` content is exposed separately to the main `body` content. + +As with ``, `` and ``, this element may only appear at the top level of your component and must never be inside a block or element. + +```svelte + + Hello world! + + +``` diff --git a/apps/svelte.dev/content/docs/svelte/05-special-elements/05-svelte-element.md b/apps/svelte.dev/content/docs/svelte/05-special-elements/05-svelte-element.md new file mode 100644 index 0000000000..17ce06799c --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-special-elements/05-svelte-element.md @@ -0,0 +1,31 @@ +--- +title: +--- + +```svelte + +``` + +The `` element lets you render an element that is unknown at author time, for example because it comes from a CMS. Any properties and event listeners present will be applied to the element. + +The only supported binding is `bind:this`, since Svelte's built-in bindings do not work with generic elements. + +If `this` has a nullish value, the element and its children will not be rendered. + +If `this` is the name of a [void element](https://developer.mozilla.org/en-US/docs/Glossary/Void_element) (e.g., `br`) and `` has child elements, a runtime error will be thrown in development mode: + +```svelte + + + + This text cannot appear inside an hr element + +``` + +Svelte tries its best to infer the correct namespace from the element's surroundings, but it's not always possible. You can make it explicit with an `xmlns` attribute: + +```svelte + +``` diff --git a/apps/svelte.dev/content/docs/svelte/05-special-elements/06-svelte-options.md b/apps/svelte.dev/content/docs/svelte/05-special-elements/06-svelte-options.md new file mode 100644 index 0000000000..142152ae9c --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-special-elements/06-svelte-options.md @@ -0,0 +1,22 @@ +--- +title: +--- + +```svelte + +``` + +The `` element provides a place to specify per-component compiler options, which are detailed in the [compiler section](svelte-compiler#compile). The possible options are: + +- `immutable={true}` — you never use mutable data, so the compiler can do simple referential equality checks to determine if values have changed +- `immutable={false}` — the default. Svelte will be more conservative about whether or not mutable objects have changed +- `accessors={true}` — adds getters and setters for the component's props +- `accessors={false}` — the default +- `runes={true}` — forces a component into _runes mode_ (see the [Legacy APIs](legacy-overview) section) +- `runes={false}` — forces a component into _legacy mode_ +- `namespace="..."` — the namespace where this component will be used, most commonly "svg"; use the "foreign" namespace to opt out of case-insensitive attribute names and HTML-specific warnings +- `customElement={...}` — the [options](custom-elements#Component-options) to use when compiling this component as a custom element. If a string is passed, it is used as the `tag` option + +```svelte + +``` diff --git a/apps/svelte.dev/content/docs/svelte/05-special-elements/09-special-elements.md b/apps/svelte.dev/content/docs/svelte/05-special-elements/09-special-elements.md deleted file mode 100644 index 13630fdea1..0000000000 --- a/apps/svelte.dev/content/docs/svelte/05-special-elements/09-special-elements.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Special elements ---- - -- [basically what we have in the docs today](https://svelte.dev/docs/special-elements) - -Some of Svelte's concepts need special elements. Those are prefixed with `svelte:` and listed here. - -## `` - -The `` element allows a component to include itself, recursively. - -It cannot appear at the top level of your markup; it must be inside an if or each block or passed to a component's slot to prevent an infinite loop. - -```svelte - - -{#if count > 0} -

    counting down... {count}

    - -{:else} -

    lift-off!

    -{/if} -``` - -## `` - -```svelte - -``` - -The `` element renders a component dynamically, using the component constructor specified as the `this` property. When the property changes, the component is destroyed and recreated. - -If `this` is falsy, no component is rendered. - -```svelte - -``` - -## `` - -```svelte - -``` - -The `` element lets you render an element of a dynamically specified type. This is useful for example when displaying rich text content from a CMS. Any properties and event listeners present will be applied to the element. - -The only supported binding is `bind:this`, since the element type-specific bindings that Svelte does at build time (e.g. `bind:value` for input elements) do not work with a dynamic tag type. - -If `this` has a nullish value, the element and its children will not be rendered. - -If `this` is the name of a [void element](https://developer.mozilla.org/en-US/docs/Glossary/Void_element) (e.g., `br`) and `` has child elements, a runtime error will be thrown in development mode. - -```svelte - - -Foo -``` - -Svelte tries its best to infer the correct namespace from the element's surroundings, but it's not always possible. You can make it explicit with an `xmlns` attribute: - -```svelte - -``` - -## `` - -```svelte - -``` - -```svelte - -``` - -The `` element allows you to add event listeners to the `window` object without worrying about removing them when the component is destroyed, or checking for the existence of `window` when server-side rendering. - -Unlike ``, this element may only appear at the top level of your component and must never be inside a block or element. - -```svelte - - - -``` - -You can also bind to the following properties: - -- `innerWidth` -- `innerHeight` -- `outerWidth` -- `outerHeight` -- `scrollX` -- `scrollY` -- `online` — an alias for `window.navigator.onLine` -- `devicePixelRatio` - -All except `scrollX` and `scrollY` are readonly. - -```svelte - -``` - -> [!NOTE] Note that the page will not be scrolled to the initial value to avoid accessibility issues. Only subsequent changes to the bound variable of `scrollX` and `scrollY` will cause scrolling. However, if the scrolling behaviour is desired, call `scrollTo()` in `onMount()`. - -## `` - -```svelte - -``` - -```svelte - -``` - -Similarly to ``, this element allows you to add listeners to events on `document`, such as `visibilitychange`, which don't fire on `window`. It also lets you use [actions](use) on `document`. - -As with ``, this element may only appear the top level of your component and must never be inside a block or element. - -```svelte - -``` - -You can also bind to the following properties: - -- `activeElement` -- `fullscreenElement` -- `pointerLockElement` -- `visibilityState` - -All are readonly. - -## `` - -```svelte - -``` - -Similarly to ``, this element allows you to add listeners to events on `document.body`, such as `mouseenter` and `mouseleave`, which don't fire on `window`. It also lets you use [actions](use) on the `` element. - -As with `` and ``, this element may only appear the top level of your component and must never be inside a block or element. - -```svelte - -``` - -## `` - -```svelte -... -``` - -This element makes it possible to insert elements into `document.head`. During server-side rendering, `head` content is exposed separately to the main `html` content. - -As with ``, `` and ``, this element may only appear at the top level of your component and must never be inside a block or element. - -```svelte - - Hello world! - - -``` - -## `` - -```svelte - -``` - -The `` element provides a place to specify per-component compiler options, which are detailed in the [compiler section](svelte-compiler#compile). The possible options are: - -- `immutable={true}` — you never use mutable data, so the compiler can do simple referential equality checks to determine if values have changed -- `immutable={false}` — the default. Svelte will be more conservative about whether or not mutable objects have changed -- `accessors={true}` — adds getters and setters for the component's props -- `accessors={false}` — the default -- `namespace="..."` — the namespace where this component will be used, most commonly "svg"; use the "foreign" namespace to opt out of case-insensitive attribute names and HTML-specific warnings -- `customElement={...}` — the [options](custom-elements#Component-options) to use when compiling this component as a custom element. If a string is passed, it is used as the `tag` option - -```svelte - -``` diff --git a/apps/svelte.dev/content/docs/svelte/06-runtime/01-stores.md b/apps/svelte.dev/content/docs/svelte/06-runtime/01-stores.md index d7fb4f552f..43bd38580a 100644 --- a/apps/svelte.dev/content/docs/svelte/06-runtime/01-stores.md +++ b/apps/svelte.dev/content/docs/svelte/06-runtime/01-stores.md @@ -2,9 +2,9 @@ title: Stores --- -- how to use + A _store_ is an object that allows reactive access to a value via a simple _store contract_. The [`svelte/store` module](../svelte-store) contains minimal store implementations which fulfil this contract. diff --git a/apps/svelte.dev/content/docs/svelte/06-runtime/02-context.md b/apps/svelte.dev/content/docs/svelte/06-runtime/02-context.md index 6314a32740..2ff015e2c1 100644 --- a/apps/svelte.dev/content/docs/svelte/06-runtime/02-context.md +++ b/apps/svelte.dev/content/docs/svelte/06-runtime/02-context.md @@ -2,8 +2,8 @@ title: Context --- -- get/set/hasContext -- how to use, best practises (like encapsulating them) + Most state is component-level state that lives as long as its component lives. There's also section-wide or app-wide state however, which also needs to be handled somehow. diff --git a/apps/svelte.dev/content/docs/svelte/06-runtime/03-lifecycle-hooks.md b/apps/svelte.dev/content/docs/svelte/06-runtime/03-lifecycle-hooks.md index 2c60c7cad6..2310d28714 100644 --- a/apps/svelte.dev/content/docs/svelte/06-runtime/03-lifecycle-hooks.md +++ b/apps/svelte.dev/content/docs/svelte/06-runtime/03-lifecycle-hooks.md @@ -2,10 +2,10 @@ title: Lifecycle hooks --- -- onMount/onDestroy + In Svelte 5, the component lifecycle consists of only two parts: Its creation and its destruction. Everything in-between - when certain state is updated - is not related to the component as a whole, only the parts that need to react to the state change are notified. This is because under the hood the smallest unit of change is actually not a component, it's the (render) effects that the component sets up upon component initialization. Consequently, there's no such thing as a "before update"/"after update" hook. diff --git a/apps/svelte.dev/content/docs/svelte/06-runtime/04-imperative-component-api.md b/apps/svelte.dev/content/docs/svelte/06-runtime/04-imperative-component-api.md index a124a86ba4..ffd03d85a6 100644 --- a/apps/svelte.dev/content/docs/svelte/06-runtime/04-imperative-component-api.md +++ b/apps/svelte.dev/content/docs/svelte/06-runtime/04-imperative-component-api.md @@ -2,13 +2,13 @@ title: Imperative component API --- -better title needed? + Every Svelte application starts by imperatively creating a root component. On the client this component is mounted to a specific element. On the server, you want to get back a string of HTML instead which you can render. The following functions help you achieve those tasks. diff --git a/apps/svelte.dev/content/docs/svelte/07-misc/04-custom-elements.md b/apps/svelte.dev/content/docs/svelte/07-misc/04-custom-elements.md index 39659f1950..48e1d1f698 100644 --- a/apps/svelte.dev/content/docs/svelte/07-misc/04-custom-elements.md +++ b/apps/svelte.dev/content/docs/svelte/07-misc/04-custom-elements.md @@ -36,7 +36,7 @@ document.body.innerHTML = ` `; ``` -Any [props](basic-markup#Attributes-and-props) are exposed as properties of the DOM element (as well as being readable/writable as attributes, where possible). +Any [props](basic-markup#Component-props) are exposed as properties of the DOM element (as well as being readable/writable as attributes, where possible). ```js // @noErrors diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md index a0e7c3dd40..2eabff6958 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md @@ -59,7 +59,7 @@ The `render` function passed to `createRawSnippet` should return HTML for a sing ### legacy_recursive_reactive_block ``` -Detected a migrated `$:` reactive block that both accesses and updates the same reactive value. This may cause recursive updates when converted to an `$effect`. +Detected a migrated `$:` reactive block in `%filename%` that both accesses and updates the same reactive value. This may cause recursive updates when converted to an `$effect`. ``` ### lifecycle_double_unmount diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/00-legacy-overview.md b/apps/svelte.dev/content/docs/svelte/99-legacy/00-legacy-overview.md new file mode 100644 index 0000000000..0840b2256e --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/00-legacy-overview.md @@ -0,0 +1,12 @@ +--- +title: Overview +--- + +Svelte 5 introduced some significant changes to Svelte's API, including [runes](what-are-runes), [snippets](snippet) and event attributes. As a result, some Svelte 3/4 features are deprecated (though supported for now, unless otherwise specified) and will eventually be removed. We recommend that you incrementally [migrate your existing code](v5-migration-guide). + +The following pages document these features for + +- people still using Svelte 3/4 +- people using Svelte 5, but with components that haven't yet been migrated + +Since Svelte 3/4 syntax still works in Svelte 5, we will distinguish between _legacy mode_ and _runes mode_. Once a component is in runes mode (which you can opt into by using runes, or by explicitly setting the `runes: true` compiler option), legacy mode features are no longer available. diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/01-legacy-let.md b/apps/svelte.dev/content/docs/svelte/99-legacy/01-legacy-let.md new file mode 100644 index 0000000000..0d1a0a72bf --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/01-legacy-let.md @@ -0,0 +1,34 @@ +--- +title: Reactive let/var declarations +--- + +In runes mode, reactive state is explicitly declared with the [`$state` rune]($state). + +In legacy mode, variables declared at the top level of a component are automatically considered _reactive_. Reassigning or mutating these variables (`count += 1` or `object.x = y`) will cause the UI to update. + +```svelte + + + +``` + +Because Svelte's legacy mode reactivity is based on _assignments_, using array methods like `.push()` and `.splice()` won't automatically trigger updates. A subsequent assignment is required to 'tell' the compiler to update the UI: + +```svelte + +``` diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/02-legacy-reactive-assignments.md b/apps/svelte.dev/content/docs/svelte/99-legacy/02-legacy-reactive-assignments.md new file mode 100644 index 0000000000..5f7c9da790 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/02-legacy-reactive-assignments.md @@ -0,0 +1,87 @@ +--- +title: Reactive $: statements +--- + +In runes mode, reactions to state updates are handled with the [`$derived`]($derived) and [`$effect`]($effect) runes. + +In legacy mode, any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with a `$:` [label](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label). These statements run after other code in the ` +``` + +Statements are ordered _topologically_ by their dependencies and their assignments: since the `console.log` statement depends on `sum`, `sum` is calculated first even though it appears later in the source. + +Multiple statements can be combined by putting them in a block: + +```js +// @noErrors +$: { + // recalculate `total` when `items` changes + total = 0; + + for (const item of items) { + total += item.value; + } +} +``` + +The left-hand side of a reactive assignments can be an identifier, or it can be a destructuring assignment: + +```js +// @noErrors +$: ({ larry, moe, curly } = stooges); +``` + +## Understanding dependencies + +The dependencies of a `$:` statement are determined at compile time — they are whichever variables are referenced (but not assigned to) inside the statement. + +In other words, a statement like this will _not_ re-run when `count` changes, because the compiler cannot 'see' the dependency: + +```js +// @noErrors +let count = 0; +let double = () => count * 2; + +$: doubled = double(); +``` + +Similarly, topological ordering will fail if dependencies are referenced indirectly: `z` will never update, because `y` is not considered 'dirty' when the update occurs. Moving `$: z = y` below `$: setY(x)` will fix it: + +```svelte + +``` + +## Browser-only code + +Reactive statements run during server-side rendering as well as in the browser. This means that any code that should only run in the browser must be wrapped in an `if` block: + +```js +// @noErrors +$: if (browser) { + document.title = title; +} +``` diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/03-legacy-export-let.md b/apps/svelte.dev/content/docs/svelte/99-legacy/03-legacy-export-let.md new file mode 100644 index 0000000000..877e105b1f --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/03-legacy-export-let.md @@ -0,0 +1,72 @@ +--- +title: export let +--- + +In runes mode, [component props](basic-markup#Component-props) are declared with the [`$props`]($props) rune, allowing parent components to pass in data. + +In legacy mode, props are marked with the `export` keyword, and can have a default value: + +```svelte + +``` + +The default value is used if it would otherwise be `undefined` when the component is created. + +> [!NOTE] Unlike in runes mode, if the parent component changes a prop from a defined value to `undefined`, it does not revert to the initial value. + +Props without default values are considered _required_, and Svelte will print a warning during development if no value is provided, which you can squelch by specifying `undefined` as the default value: + +```js +export let foo +++= undefined;+++ +``` + +## Component exports + +An exported `const`, `class` or `function` declaration is _not_ considered a prop — instead, it becomes part of the component's API: + +```svelte + + +``` + +```svelte + + + + + + +``` + +## Renaming props + +The `export` keyword can appear separately from the declaration. This is useful for renaming props, for example in the case of a reserved word: + +```svelte + + +``` diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/04-legacy-$$props-and-$$restProps.md b/apps/svelte.dev/content/docs/svelte/99-legacy/04-legacy-$$props-and-$$restProps.md new file mode 100644 index 0000000000..33cac97035 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/04-legacy-$$props-and-$$restProps.md @@ -0,0 +1,30 @@ +--- +title: $$props and $$restProps +--- + +In runes mode, getting an object containing all the props that were passed in is easy, using the [`$props`]($props) rune. + +In legacy mode, we use `$$props` and `$$restProps`: + +- `$$props` contains all the props that were passed in, including ones that are not individually declared with the `export` keyword +- `$$restProps` contains all the props that were passed in _except_ the ones that were individually declared + +For example, a ` + + +``` + +In Svelte 3/4 using `$$props` and `$$restProps` creates a modest performance penalty, so they should only be used when needed. diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/10-legacy-on.md b/apps/svelte.dev/content/docs/svelte/99-legacy/10-legacy-on.md new file mode 100644 index 0000000000..f2ee694cc1 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/10-legacy-on.md @@ -0,0 +1,136 @@ +--- +title: on: +--- + +In runes mode, event handlers are just like any other attribute or prop. + +In legacy mode, we use the `on:` directive: + +```svelte + + + + +``` + +Handlers can be declared inline with no performance penalty: + +```svelte + +``` + +Add _modifiers_ to element event handlers with the `|` character. + +```svelte + + + +``` + +The following modifiers are available: + +- `preventDefault` — calls `event.preventDefault()` before running the handler +- `stopPropagation` — calls `event.stopPropagation()`, preventing the event reaching the next element +- `stopImmediatePropagation` - calls `event.stopImmediatePropagation()`, preventing other listeners of the same event from being fired. +- `passive` — improves scrolling performance on touch/wheel events (Svelte will add it automatically where it's safe to do so) +- `nonpassive` — explicitly set `passive: false` +- `capture` — fires the handler during the _capture_ phase instead of the _bubbling_ phase +- `once` — remove the handler after the first time it runs +- `self` — only trigger handler if `event.target` is the element itself +- `trusted` — only trigger handler if `event.isTrusted` is `true`. I.e. if the event is triggered by a user action. + +Modifiers can be chained together, e.g. `on:click|once|capture={...}`. + +If the `on:` directive is used without a value, the component will _forward_ the event, meaning that a consumer of the component can listen for it. + +```svelte + +``` + +It's possible to have multiple event listeners for the same event: + +```svelte + + + + +``` + +## Component events + +Components can dispatch events by creating a _dispatcher_ when they are initialised: + +```svelte + + + + + +``` + +`dispatch` creates a [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). If a second argument is provided, it becomes the `detail` property of the event object. + +A consumer of this component can listen for the dispatched events: + +```svelte + + + n -= 1} + on:increment={() => n += 1} +/> + +

    n: {n}

    +``` + +Component events do not bubble — a parent component can only listen for events on its immediate children. + +Other than `once`, modifiers are not valid on component event handlers. + +> [!NOTE] +> If you're planning an eventual migration to Svelte 5, use callback props instead. This will make upgrading easier as `createEventDispatcher` is deprecated: +> +> ```svelte +> +> +> +> +> +> ``` diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/20-legacy-slots.md b/apps/svelte.dev/content/docs/svelte/99-legacy/20-legacy-slots.md new file mode 100644 index 0000000000..5189f2017d --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/20-legacy-slots.md @@ -0,0 +1,116 @@ +--- +title: +--- + +In Svelte 5, content can be passed to components in the form of [snippets](snippet) and rendered using [render tags](@render). + +In legacy mode, content inside component tags is considered _slotted content_, which can be rendered by the component using a `` element: + +```svelte + + + +This is some slotted content +``` + +```svelte + +
    + +
    +``` + +> [!NOTE] If you want to render a regular `` element, you can use ``. + +## Named slots + +A component can have _named_ slots in addition to the default slot. On the parent side, add a `slot="..."` attribute to an element, component or [``](legacy-svelte-fragment) directly inside the component tags. + +```svelte + + + +{#if open} + + This is some slotted content + + +++
    +++ + + +++
    +++ +     +{/if} +``` + +On the child side, add a corresponding `` element: + +```svelte + +
    + +
    + ++++++ +
    +``` + +## Fallback content + +If no slotted content is provided, a component can define fallback content by putting it inside the `` element: + +```svelte + + This will be rendered if no slotted content is provided + +``` + +## Passing data to slotted content + +Slots can be rendered zero or more times and can pass values _back_ to the parent using props. The parent exposes the values to the slot template using the `let:` directive. + +The usual shorthand rules apply — `let:item` is equivalent to `let:item={item}`, and `` is equivalent to ``. + +```svelte + +
      + {#each items as item} +
    • + +
      • + {/each} +
    + + + +
    {thing.text}
    +     +``` + +Named slots can also expose values. The `let:` directive goes on the element with the `slot` attribute. + +```svelte + +
      + {#each items as item} +
    • + +
      • + {/each} +
    + + + + + +
    {item.text}
    +

    Copyright (c) 2019 Svelte Industries

    +     +``` + + diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/21-legacy-$$slots.md b/apps/svelte.dev/content/docs/svelte/99-legacy/21-legacy-$$slots.md new file mode 100644 index 0000000000..7ca1cef844 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/21-legacy-$$slots.md @@ -0,0 +1,27 @@ +--- +title: $$slots +--- + +In runes mode, we know which [snippets](snippet) were provided to a component, as they're just normal props. + +In legacy mode, the way to know if content was provided for a given slot is with the `$$slots` object, whose keys are the names of the slots passed into the component by the parent. + +```svelte + +
    + + {#if $$slots.description} + +
    + + {/if} +
    +``` + +```svelte + + +

    Blog Post Title

    + +     +``` diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md b/apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md new file mode 100644 index 0000000000..8827ab53cb --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md @@ -0,0 +1,32 @@ +--- +title: +--- + +The `` element allows you to place content in a [named slot](/docs/special-elements#slot-slot-name-name) without wrapping it in a container DOM element. This keeps the flow layout of your document intact. + +```svelte + +
    + No header was provided +

    Some content between header and footer

    + +
    +``` + +```svelte + + + + +

    Hello

    + +

    All rights reserved.

    +

    Copyright (c) 2019 Svelte Industries

    +     +     +``` + +> [!NOTE] +> In Svelte 5+, this concept is obsolete, as snippets don't create a wrapping element diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/30-legacy-svelte-component.md b/apps/svelte.dev/content/docs/svelte/99-legacy/30-legacy-svelte-component.md new file mode 100644 index 0000000000..5d385a9c02 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/30-legacy-svelte-component.md @@ -0,0 +1,13 @@ +--- +title: +--- + +In runes mode, `` will re-render if the value of `MyComponent` changes. + +In legacy mode, it won't — we must use ``, which destroys and recreates the component instance when the value of its `this` expression changes: + +```svelte + +``` + +If `this` is falsy, no component is rendered. diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/31-legacy-svelte-self.md b/apps/svelte.dev/content/docs/svelte/99-legacy/31-legacy-svelte-self.md new file mode 100644 index 0000000000..bfd140ac49 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/31-legacy-svelte-self.md @@ -0,0 +1,37 @@ +--- +title: +--- + +The `` element allows a component to include itself, recursively. + +It cannot appear at the top level of your markup; it must be inside an if or each block or passed to a component's slot to prevent an infinite loop. + +```svelte + + +{#if count > 0} +

    counting down... {count}

    + +{:else} +

    lift-off!

    +{/if} +``` + +> [!NOTE] +> This concept is obsolete, as components can import themselves: +> ```svelte +> +> +> +> {#if count > 0} +>

    counting down... {count}

    +> +> {:else} +>

    lift-off!

    +> {/if} +> ``` diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/40-legacy-component-api.md b/apps/svelte.dev/content/docs/svelte/99-legacy/40-legacy-component-api.md new file mode 100644 index 0000000000..5bbe7e7237 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/40-legacy-component-api.md @@ -0,0 +1,200 @@ +--- +title: Imperative component API +--- + +In Svelte 3 and 4, the API for interacting with a component is different than in Svelte 5. Note that this page does _not_ apply to legacy mode components in a Svelte 5 application. + +## Creating a component + +```ts +// @noErrors +const component = new Component(options); +``` + +A client-side component — that is, a component compiled with `generate: 'dom'` (or the `generate` option left unspecified) is a JavaScript class. + +```ts +// @noErrors +import App from './App.svelte'; + +const app = new App({ + target: document.body, + props: { + // assuming App.svelte contains something like + // `export let answer`: + answer: 42 + } +}); +``` + +The following initialisation options can be provided: + +| option | default | description | +| --------- | ----------- | ---------------------------------------------------------------------------------------------------- | +| `target` | **none** | An `HTMLElement` or `ShadowRoot` to render to. This option is required | +| `anchor` | `null` | A child of `target` to render the component immediately before | +| `props` | `{}` | An object of properties to supply to the component | +| `context` | `new Map()` | A `Map` of root-level context key-value pairs to supply to the component | +| `hydrate` | `false` | See below | +| `intro` | `false` | If `true`, will play transitions on initial render, rather than waiting for subsequent state changes | + +Existing children of `target` are left where they are. + +The `hydrate` option instructs Svelte to upgrade existing DOM (usually from server-side rendering) rather than creating new elements. It will only work if the component was compiled with the [`hydratable: true` option](/docs/svelte-compiler#compile). Hydration of `` elements only works properly if the server-side rendering code was also compiled with `hydratable: true`, which adds a marker to each element in the `` so that the component knows which elements it's responsible for removing during hydration. + +Whereas children of `target` are normally left alone, `hydrate: true` will cause any children to be removed. For that reason, the `anchor` option cannot be used alongside `hydrate: true`. + +The existing DOM doesn't need to match the component — Svelte will 'repair' the DOM as it goes. + +```ts +/// file: index.js +// @noErrors +import App from './App.svelte'; + +const app = new App({ + target: document.querySelector('#server-rendered-html'), + hydrate: true +}); +``` + +> [!NOTE] +> In Svelte 5+, use [`mount`](svelte#mount) instead + +## `$set` + +```ts +// @noErrors +component.$set(props); +``` + +Programmatically sets props on an instance. `component.$set({ x: 1 })` is equivalent to `x = 1` inside the component's ` + + + +``` + +The migration script will do both automatically for you. ([#8512](https://github.com/sveltejs/svelte/issues/8512)) + +## Transitions are local by default + +Transitions are now local by default to prevent confusion around page navigations. "local" means that a transition will not play if it's within a nested control flow block (`each/if/await/key`) and not the direct parent block but a block above it is created/destroyed. In the following example, the `slide` intro animation will only play when `success` goes from `false` to `true`, but it will _not_ play when `show` goes from `false` to `true`: + +```svelte +{#if show} + ... + {#if success} +

    Success

    + {/each} +{/if} +``` + +To make transitions global, add the `|global` modifier - then they will play when _any_ control flow block above is created/destroyed. The migration script will do this automatically for you. ([#6686](https://github.com/sveltejs/svelte/issues/6686)) + +## Default slot bindings + +Default slot bindings are no longer exposed to named slots and vice versa: + +```svelte + + + +

    + count in default slot - is available: {count} +

    +

    + count in bar slot - is not available: {count} +

    +     +``` + +This makes slot bindings more consistent as the behavior is undefined when for example the default slot is from a list and the named slot is not. ([#6049](https://github.com/sveltejs/svelte/issues/6049)) + +## Preprocessors + +The order in which preprocessors are applied has changed. Now, preprocessors are executed in order, and within one group, the order is markup, script, style. + +```js +// @errors: 2304 +import { preprocess } from 'svelte/compiler'; + +const { code } = await preprocess( + source, + [ + { + markup: () => { + console.log('markup-1'); + }, + script: () => { + console.log('script-1'); + }, + style: () => { + console.log('style-1'); + } + }, + { + markup: () => { + console.log('markup-2'); + }, + script: () => { + console.log('script-2'); + }, + style: () => { + console.log('style-2'); + } + } + ], + { + filename: 'App.svelte' + } +); + +// Svelte 3 logs: +// markup-1 +// markup-2 +// script-1 +// script-2 +// style-1 +// style-2 + +// Svelte 4 logs: +// markup-1 +// script-1 +// style-1 +// markup-2 +// script-2 +// style-2 +``` + +This could affect you for example if you are using `MDsveX` - in which case you should make sure it comes before any script or style preprocessor. + +```js +// @noErrors +preprocess: [ +--- vitePreprocess(), + mdsvex(mdsvexConfig)--- ++++ mdsvex(mdsvexConfig), + vitePreprocess()+++ +] +``` + +Each preprocessor must also have a name. ([#8618](https://github.com/sveltejs/svelte/issues/8618)) + +## New eslint package + +`eslint-plugin-svelte3` is deprecated. It may still work with Svelte 4 but we make no guarantees about that. We recommend switching to our new package [eslint-plugin-svelte](https://github.com/sveltejs/eslint-plugin-svelte). See [this Github post](https://github.com/sveltejs/kit/issues/10242#issuecomment-1610798405) for an instruction how to migrate. Alternatively, you can create a new project using `npm create svelte@latest`, select the eslint (and possibly TypeScript) option and then copy over the related files into your existing project. + +## Other breaking changes + +- the `inert` attribute is now applied to outroing elements to make them invisible to assistive technology and prevent interaction. ([#8628](https://github.com/sveltejs/svelte/pull/8628)) +- the runtime now uses `classList.toggle(name, boolean)` which may not work in very old browsers. Consider using a [polyfill](https://github.com/eligrey/classList.js) if you need to support these browsers. ([#8629](https://github.com/sveltejs/svelte/issues/8629)) +- the runtime now uses the `CustomEvent` constructor which may not work in very old browsers. Consider using a [polyfill](https://github.com/theftprevention/event-constructor-polyfill/tree/master) if you need to support these browsers. ([#8775](https://github.com/sveltejs/svelte/pull/8775)) +- people implementing their own stores from scratch using the `StartStopNotifier` interface (which is passed to the create function of `writable` etc) from `svelte/store` now need to pass an update function in addition to the set function. This has no effect on people using stores or creating stores using the existing Svelte stores. ([#6750](https://github.com/sveltejs/svelte/issues/6750)) +- `derived` will now throw an error on falsy values instead of stores passed to it. ([#7947](https://github.com/sveltejs/svelte/issues/7947)) +- type definitions for `svelte/internal` were removed to further discourage usage of those internal methods which are not public API. Most of these will likely change for Svelte 5 +- Removal of DOM nodes is now batched which slightly changes its order, which might affect the order of events fired if you're using a `MutationObserver` on these elements ([#8763](https://github.com/sveltejs/svelte/pull/8763)) +- if you enhanced the global typings through the `svelte.JSX` namespace before, you need to migrate this to use the `svelteHTML` namespace. Similarly if you used the `svelte.JSX` namespace to use type definitions from it, you need to migrate those to use the types from `svelte/elements` instead. You can find more information about what to do [here](https://github.com/sveltejs/language-tools/blob/master/docs/preprocessors/typescript.md#im-getting-deprecation-warnings-for-sveltejsx--i-want-to-migrate-to-the-new-typings) diff --git a/apps/svelte.dev/content/docs/svelte/07-misc/05-reactivity-indepth.md b/apps/svelte.dev/content/docs/svelte/07-misc/xx-reactivity-indepth.md similarity index 100% rename from apps/svelte.dev/content/docs/svelte/07-misc/05-reactivity-indepth.md rename to apps/svelte.dev/content/docs/svelte/07-misc/xx-reactivity-indepth.md diff --git a/apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md b/apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md index 8827ab53cb..779931f947 100644 --- a/apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md +++ b/apps/svelte.dev/content/docs/svelte/99-legacy/22-legacy-svelte-fragment.md @@ -2,7 +2,7 @@ title: --- -The `` element allows you to place content in a [named slot](/docs/special-elements#slot-slot-name-name) without wrapping it in a container DOM element. This keeps the flow layout of your document intact. +The `` element allows you to place content in a [named slot](legacy-slots) without wrapping it in a container DOM element. This keeps the flow layout of your document intact. ```svelte From 3240e9322c3527a4dd144b0bd628b7d4172ed4f7 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Tue, 22 Oct 2024 02:12:28 -0400 Subject: [PATCH 3/3] sync --- ...024-07-01-whats-new-in-svelte-july-2024.md | 82 ++++++++++++++++ ...4-08-01-whats-new-in-svelte-august-2024.md | 94 ++++++++++++++++++ ...9-01-whats-new-in-svelte-september-2024.md | 81 +++++++++++++++ ...-10-01-whats-new-in-svelte-october-2024.md | 98 +++++++++++++++++++ .../svelte/07-misc/06-v4-migration-guide.md | 2 +- 5 files changed, 356 insertions(+), 1 deletion(-) create mode 100644 apps/svelte.dev/content/blog/2024-07-01-whats-new-in-svelte-july-2024.md create mode 100644 apps/svelte.dev/content/blog/2024-08-01-whats-new-in-svelte-august-2024.md create mode 100644 apps/svelte.dev/content/blog/2024-09-01-whats-new-in-svelte-september-2024.md create mode 100644 apps/svelte.dev/content/blog/2024-10-01-whats-new-in-svelte-october-2024.md diff --git a/apps/svelte.dev/content/blog/2024-07-01-whats-new-in-svelte-july-2024.md b/apps/svelte.dev/content/blog/2024-07-01-whats-new-in-svelte-july-2024.md new file mode 100644 index 0000000000..82e24c98f1 --- /dev/null +++ b/apps/svelte.dev/content/blog/2024-07-01-whats-new-in-svelte-july-2024.md @@ -0,0 +1,82 @@ +--- +title: "What's new in Svelte: July 2024" +description: 'svelte/events, simpler elements and more optional options' +author: Dani Sandoval +authorURL: https://dreamindani.com +--- + +This month, we got a bunch of new features in the Svelte 5 release candidate, Rich Harris [explained to Prismic's CEO](https://www.youtube.com/live/uWLTDUjNrhQ) how Svelte optimizes for vibes and Geoff Rich [shared even more about this philosophy at CascadiaJS 2024](https://cascadiajs.com/2024/talks/optimize-for-vibes-svelte-5-and-the-new-age-of-svelte). + +Let's jump in! + +## What's new in Svelte + +Below, you'll find the highlights from the Svelte 5 release notes (now in [Release Candidate](https://www.npmjs.com/package/svelte?activeTab=versions)): + +- You can now declare props in runes mode more succinctly using `let props = $props()` (**5.0.0-next.167**, [#12201](https://github.com/sveltejs/svelte/pull/12201)) +- The new `on` import from `svelte/events` allows you to preserve the order in which event handlers are called in more situations (**5.0.0-next.152**, [Docs](https://svelte-5-preview.vercel.app/docs/imports#svelte-events), [#11912](https://github.com/sveltejs/svelte/pull/11912)) +- The `Component` type now represents the new shape of Svelte components (**5.0.0-next.143**, [#11775](https://github.com/sveltejs/svelte/pull/11775)) +- `` has new `activeElement` and `pointerLockElement` bindings (**5.0.0-next.150**, [#11879](https://github.com/sveltejs/svelte/pull/11879)) +- ``, CSS custom property wrappers and string normalization have all been simplified and made more performant (**5.0.0-next.152**, [#11773](https://github.com/sveltejs/svelte/pull/11773), [#11948](https://github.com/sveltejs/svelte/pull/11948), [#11954](https://github.com/sveltejs/svelte/pull/11954), [#11792](https://github.com/sveltejs/svelte/pull/11792), [#11949](https://github.com/sveltejs/svelte/pull/11949)) +- `render`, `mount` and `hydrate` options are now actually optional if no properties are required (**5.0.0-next.163**, [Docs](https://svelte-5-preview.vercel.app/docs/imports#svelte), [#12111](https://github.com/sveltejs/svelte/pull/12111)) + +## What's new in SvelteKit + +The node and Cloudflare adapters got a few upgrades this month: + +- The `BODY_SIZE_LIMIT` environment variable adds unit suffixes support to the adapter-node - making it easier to write and comprehend large byte values (**adapter-node@5.2.0**, [Docs](https://kit.svelte.dev/docs/adapter-node#environment-variables-bodysizelimit), [#11680](https://github.com/sveltejs/kit/pull/11680)) +- Node servers can now listen to the `sveltekit:shutdown` event (replacing the more abrupt `exit`) that is emitted after the HTTP server has closed all connections (**adapter-node@5.1.0**, [Docs](https://kit.svelte.dev/docs/adapter-node#graceful-shutdown), [#12153](https://github.com/sveltejs/kit/pull/12153)) +- The Cloudflare adapter will now only throw a `_routes.json` error when the file exists but there are no configured routes in svelte.config (**adapter-cloudflare@4.5.0**, [#12360](https://github.com/sveltejs/kit/pull/12360)) + +--- + +## Community Showcase + +### Apps & Sites built with Svelte + +- [Shootmail](https://shootmail.app/) is an email template and content creation tool +- [wplatest](https://wplatest.co/) automates your WordPress plugin updates across multiple websites +- [Svelte-MiniApps](https://github.com/Michael-Obele/Svelte-MiniApps) is a collection of bite-sized, user-friendly tools built with SvelteKit +- [Interior Render AI](https://www.interiorrenderai.com/) redesigns your interior with AI in seconds + +### Learning Resources + +_Featuring Svelte Contributors and Ambassadors_ + +- [Prismic 🧡 Svelte: Meetup with Rich Harris, creator of Svelte!](https://www.youtube.com/live/uWLTDUjNrhQ) by Prismic +- [How Svelte and RSCs are Changing Web Development with Rich Harris, Creator of Svelte](https://www.youtube.com/watch?v=QTJtR8IUsQM) by This Dot Media +- [Learn Why JavaScript Frameworks Love Signals By Implementing Them](https://www.youtube.com/watch?app=desktop&v=1TSLEzNzGQM) and [The Svelte 5 Reactivity Guide For The Modern Developer](https://www.youtube.com/watch?v=tErKyuUTzsM) and [Crafting Magical Spells Using Svelte's Powerful Reactivity](https://www.youtube.com/watch?v=HnNgkwHZIII) by Joy Of Code +- [Practical Svelte 5 - Shopping Cart](https://www.youtube.com/watch?v=geAcAzheu_Y) by Huntabyte +- [CascadiaJS 2024: Optimize for vibes](https://geoffrich.net/posts/cascadiajs-2024/) by Geoff Rich (Livestream of Geoff's talk [starts at 1:08:30](https://www.youtube.com/live/o2VQXBI_yk8?si=Vv4FSZ367dC50Ii7&t=4110)) +- This Week in Svelte - deep dives into the Svelte changelog and new learnings from the week: + - [Ep. 66](https://www.youtube.com/watch?v=yaAGazsz6Lc) - adapter-node, new SvelteKit docs, Debugging Event modifiers in Svelte 5 + - [7 Jun](https://www.youtube.com/watch?v=5JNcz7mOfMI) - Validation libraries, $effect.active() usage + - [31 May](https://www.youtube.com/watch?v=edoYKNgUQQI) - Floating UI, StartStopNotifier +- Svelte Society Vienna + - [Ermin Celikovic — Building Web Components using Svelte](https://www.youtube.com/watch?v=T4zwmtUW7Gw) + - [Domenik Reitzner — Svelte 5 Runes explained for Vue devs](https://www.youtube.com/watch?v=4idUQlFV02I) +- [Svelte London — June 2024](https://www.youtube.com/watch?v=J5srLwhlBdw) +- [Svelte Dev Vlog — June 2024](https://www.youtube.com/watch?v=4TGwlWFoGvM) with Rich Harris + +_To Read_ + +- [Lessons using sveltekit to build a dataviz platform](https://www.reddit.com/r/sveltejs/comments/1dggvhh/lessons_using_sveltekit_to_build_a_dataviz/) by DNLBLN on Reddit +- [Frontend Frameworks in 2024 for eCommerce](https://crystallize.com/blog/best-frontend-frameworks?utm_medium=social&utm_source=Discord) by Crystallize +- [Using Unplugin Icons in SvelteKit: A Step-by-Step Guide](https://www.launchfa.st/blog/sveltekit-unplugin-icons) by Rishi Raj Jain +- [Migrating Tronic247 from WordPress to SvelteKit](https://www.tronic247.com/migrating-tronic247-from-wordpress-to-sveltekit?_) and [Methods to Load Data in Svelte and SvelteKit](https://www.tronic247.com/methods-to-load-data-in-svelte) by tronic247 + +_To Watch_ + +- [The Easiest Way to Build Web Apps](https://www.youtube.com/watch?v=ZT0yQgUIZho) and [13 Svelte Concepts you Need to Know](https://www.youtube.com/watch?v=A-6MVm0yt20) by Awesome +- [SvelteKit Form Validation with Zod](https://www.youtube.com/watch?v=11AbCRomRhs) by Ross Robino +- [Bringing together Auth and Payments with AirBadge](https://www.youtube.com/watch?v=6w3v9QD2ae4) by Stripe Developers +- [Svelte 4 vs. Svelte 5 – Runes and Snippets](https://www.youtube.com/watch?v=X37exLLQHwg) by SvelteRust + +### Libraries, Tools & Components + +- [svelte5-commenter](https://github.com/cardgraph22/svelte5-commenter) is a component demonstration for the common comments section +- [SSC](https://github.com/ssc-project/ssc) (Speedy Svelte Compiler) is a super-fast Svelte compiler written in Rust + +That's it for this month! Let us know if we missed anything on [Reddit](https://www.reddit.com/r/sveltejs/) or [Discord](https://discord.gg/svelte). + +Until next month 👋 diff --git a/apps/svelte.dev/content/blog/2024-08-01-whats-new-in-svelte-august-2024.md b/apps/svelte.dev/content/blog/2024-08-01-whats-new-in-svelte-august-2024.md new file mode 100644 index 0000000000..3a335e77a2 --- /dev/null +++ b/apps/svelte.dev/content/blog/2024-08-01-whats-new-in-svelte-august-2024.md @@ -0,0 +1,94 @@ +--- +title: "What's new in Svelte: August 2024" +description: 'Significant hydration improvements, customizable warnings, and a new API: `createRawSnippet`' +author: Dani Sandoval +authorURL: https://dreamindani.com +--- + +The ramp up to the Svelte 5 release has led to a bunch of huge improvements to both performance and customizability. Also in this month's round-up: some minor SvelteKit updates and a return of the Svelte Dev Vlog. + +Let's dive in! + +## What's new in Svelte + +Below, you'll find the highlights from the Svelte 5 release notes (currently in [Release Candidate](https://www.npmjs.com/package/svelte?activeTab=versions)): + +- Breaking: The names of the `svelte/reactivity` helpers have been updated to include a `Svelte` prefix (**5.0.0-next.169**, [Docs](https://svelte-5-preview.vercel.app/docs/imports#svelte-reactivity) [#12248](https://github.com/sveltejs/svelte/pull/12248)) +- Branch effects now have better DOM boundaries - reducing bugs in `{#each}` blocks and during DOM manipulation (**5.0.0-next.171** and **5.0.0-next.182**, [#12215](https://github.com/sveltejs/svelte/pull/12215), [#12258](https://github.com/sveltejs/svelte/pull/12258), [#12383](https://github.com/sveltejs/svelte/pull/12383)) +- Single-pass hydration has reduced DOM size and significantly improved hydration speed (**5.0.0-next.179**, [#12335](https://github.com/sveltejs/svelte/pull/12335), [#12339](https://github.com/sveltejs/svelte/pull/12339)) +- Breaking: Transitions now play on mount by default (**5.0.0-next.177**, [#12351](https://github.com/sveltejs/svelte/pull/12351)) +- CSS can now be included in the `` when the `css: 'injected'` compiler option is enabled. This makes it trivial to include styles when rendering things like emails and OG cards, as well as massively simplifying toy setups where you can't be bothered to figure out how to get CSS from the compiler into your server-rendered HTML (**5.0.0-next.180**, [Docs](https://svelte-5-preview.vercel.app/docs/imports#svelte-server-render), [#12374](https://github.com/sveltejs/svelte/pull/12374)) +- Svelte will now warn in dev on `{@html ...}` block hydration mismatches (**5.0.0-next.182**, [#12396](https://github.com/sveltejs/svelte/pull/12396)) +- The new `warningFilter` compiler option lets you disable certain warnings for the whole application without having to add `svelte-ignore` comments everywhere (**5.0.0-next.186**, [#12296](https://github.com/sveltejs/svelte/pull/12296)) +- The new `createRawSnippet` API, allows low-level creation of programmatic snippets outside of Svelte templates (**5.0.0-next.189**, [Docs](https://svelte-5-preview.vercel.app/docs/imports#svelte-createrawsnippet), [#12425](https://github.com/sveltejs/svelte/pull/12425)) + +## What's new in SvelteKit and beyond + +- The HTML attributes `enctype` and `formenctype` are now respected for forms with `use:enhance` (plus, some other bug fixes in the [CHANGELOG](https://github.com/sveltejs/kit/blob/main/packages/kit/CHANGELOG.md)) +- The cloudflare, cloudflare-workers, netlify and vercel adapters have all been updated to copy `.eot`, `.otf`, .`ttf`, `.woff`, and `.woff2` font files when bundling ([CHANGELOGs](https://github.com/sveltejs/kit/tree/main/packages)) +- `svelte-preprocess`, the tool used in nearly every Svelte project, is now dependency free! The team has gradually reduced it from 44 dependencies in 5.0.0 down to zero in the latest release ([Tweet](https://x.com/BenjaminMcCann/status/1810698991820321028)) +- prerendered redirects will now be appended to the `_redirects` file in the Cloudflare Pages adapter (**adapter-cloudflare@4.7.0**, [#12199](https://github.com/sveltejs/kit/pull/12199)) + +--- + +## Community Showcase + +### Apps & Sites built with Svelte + +- [The StackOverflow 2024 Developer Survey](https://stackoverflow.blog/2024/07/24/developers-want-more-more-more-the-2024-results-from-stack-overflow-s-annual-developer-survey/) results site was built using Svelte. Even better, the results show that 73% of developers that used it want to keep working with Svelte (More info in this [tweet](https://x.com/SvelteSociety/status/1816497535839858792)) +- [azigy](https://azigy.com/) is a live, multiplayer quiz and trivia application +- [on-device-transcription](https://github.com/Hugo-Dz/on-device-transcription) is a ready-to-use, minimal app that converts any speech into text +- [Whispering](https://github.com/braden-w/whispering) is an open-source transcription application that provides global speech-to-text functionality +- [Frogment](https://www.frogment.app/) is an OpenAPI specification editor +- [SticAI Glance](https://glance.sticai.com/) summarizes reddit post to actionable insights +- [Over Rice](https://www.overrice.nyc/) tracks the best halal carts around New York City +- [earbetter](https://github.com/ryanatkn/earbetter) is an ear trainer and tools for playing and programming music and audio +- [Moonglow](https://moonglow.app/) is a deep planetary simulation using GPGPU +- [opml-editor](https://github.com/imdj/opml-editor/) is an online OPML editor tailored for managing subscription lists more easily +- [Praxis](https://praxis.trade/) is an AI-powered trading journal that analyzes your trades and uncovers patterns +- [Lokal](https://lokal.so/) lets you share your localhost with Public and https .local Address +- [formcrafts](https://formcrafts.com/) lets you create incredible forms like application forms, lead generation forms, surveys, payment forms, and more +- [Shootmail](https://shootmail.app/) is a template-first mail platform with scheduling and analytics +- [Supersaw](https://github.com/HelgeSverre/supersaw) is Open Source Web Based Digital Audio Workstation (DAW) + +### Learning Resources + +_Featuring Svelte Contributors and Ambassadors_ + +- [Svelte Dev Vlog (with Rich) — June 2024](https://www.youtube.com/watch?v=4TGwlWFoGvM) on Svelte Society YouTube +- [Svelte London — July 2024](https://www.youtube.com/watch?v=gujnZDyLDwU) +- [Svelte Meets Vite: A Deep Dive with Matias Capeletto (patakdev)](https://www.svelteradio.com/episodes/svelte-meets-vite-a-deep-dive-with-matias-capeletto-patakdev) by Svelte Radio +- [Unleashing the Power of Claude Artifacts with Svelte and Sonnet 3.5](https://www.youtube.com/watch?v=Q7q77c5j7bQ) and [Perfect AI development setup for any programming language with Sonnet 3.5 and Claude Projects](https://www.youtube.com/watch?v=zNkw5K2W8AQ) by Stanislav Khromov +- [Local First from Scratch - How to make a web app with local data](https://www.youtube.com/watch?v=Qoqh9Mdmk80) by Syntax. +- This Week in Svelte: + - [Ep. 67](https://www.youtube.com/watch?v=9yy1s7TAvXE) — Changelog, Popover API, starting-style, resetting file inputs + - [Ep. 68](https://www.youtube.com/watch?v=G6Z0l2plyIk) — Changelog, EATView, Capacitor + - [Ep. 69](https://www.youtube.com/watch?v=sVp0RukyfYk) — Changelog, socket activation, open source support + - [Ep. 70](https://www.youtube.com/watch?v=Da-xOep6hcs) — Changelog, Taiwind CSS and Svelte Motion, when tu use $derived + +_To Read_ + +- [From React To Svelte - Our Experience as a Dev Shop](https://www.reddit.com/r/sveltejs/comments/1e5522o/from_react_to_svelte_our_experience_as_a_dev_shop/) by gimp3695 +- [Authentication in SvelteKit using SvelteKitAuth](https://blog.aakashgoplani.in/series/sveltekitauth-sveltekit) by Aakash Goplani +- [SvelteKit (Svelte 5) and Supabase](https://www.thespatula.io/svelte/sveltekit_supabase/) by the spatula +- [Firebase signInWithRedirect, localhost, and SvelteKit](https://captaincodeman.com/firebase-signinwithredirect-localhost-and-sveltekit), [Dealing with Dialogs in Svelte](https://www.captaincodeman.com/dealing-with-dialogs-in-svelte) and [Build a Docker Container from a pnpm monorepo](https://www.captaincodeman.com/build-a-docker-container-from-a-pnpm-monorepo) by Captain Codeman +- [Introducing Svelte 5](https://frontendmasters.com/blog/introducing-svelte-5/) by Frontend Masters + +_To Watch_ + +- [Introduction to Sveltekit (#1) Parahack's Let learn Sveltekit](https://www.youtube.com/watch?v=c2QqPuG6mw0&t=683s), [image optimization in sveltekit](https://www.youtube.com/watch?v=pUlWbIqdkYE) and [Deploy your sveltekit app to cloudflare pages](https://www.youtube.com/watch?v=pGS_07zP-no) by Lawal Adebola +- [How Svelte runes syntax is better than plain JavaScript with signals](https://www.youtube.com/watch?v=IsJtmbvW2SI) by webdevladder + +### Libraries, Tools & Components + +- [Sveaflet](https://sveaflet.vercel.app/) is an open-source Map component library +- [Svelte Magic UI](https://animation-svelte.vercel.app/) are componetns built using Tailwind CSS, Tweened, Spring and Svelte Motion +- [Figblocks](https://figblocks.mohanvadivel.com/) is an open-source UI component library for building Figma plugins with Svelte +- [VS Code Supports Custom Tab Labels](https://www.reddit.com/r/sveltejs/comments/1e26pfc/vs_code_supports_custom_tab_labels/) (a good reminder for folks who haven't sent it up yet) +- Storybook did a prerelease of `@storybook/addon-svelte-csf` with support for Svelte v5. If you're using it, share your feedback on their RFC: [storybookjs/addon-svelte-csf#191](https://github.com/storybookjs/addon-svelte-csf/discussions/191) +- [sveltekit-search-params](https://github.com/paoloricciuti/sveltekit-search-params) released `v3.0.0` with better types +- [optimistikit](https://github.com/paoloricciuti/optimistikit) got revamped to fully support runes in `v1.0.0` while keeping the `@legacy` tag if you still can't update from stores + +That's it for this month! Let us know if we missed anything on [Reddit](https://www.reddit.com/r/sveltejs/) or [Discord](https://discord.gg/svelte). + +Until next month 👋 diff --git a/apps/svelte.dev/content/blog/2024-09-01-whats-new-in-svelte-september-2024.md b/apps/svelte.dev/content/blog/2024-09-01-whats-new-in-svelte-september-2024.md new file mode 100644 index 0000000000..c7da4ebc83 --- /dev/null +++ b/apps/svelte.dev/content/blog/2024-09-01-whats-new-in-svelte-september-2024.md @@ -0,0 +1,81 @@ +--- +title: "What's new in Svelte: September 2024" +description: 'More useful `svelte:options` and `:global`, plus the deprecation of `` in Svelte 5' +author: Dani Sandoval +authorURL: https://dreamindani.com +--- + +A bunch of updates to Svelte dropped in the last few weeks, plus a few quality of life improvements in the Svelte language tools. + +Let's take a look... + +## What's new in Svelte and Language Tools + +- `$state.frozen` has been replaced with `$state.raw` (**5.0.0-next.218**, [Docs](https://svelte-5-preview.vercel.app/docs/runes#state-raw), [#12808](https://github.com/sveltejs/svelte/pull/12808)) +- `$state.is` has been removed. RIP, little guy ([#12916](https://github.com/sveltejs/svelte/pull/12916)) +- `svelte:options` now lets you set the `css: "inject"` compiler option on a per-component basis (**5.0.0-next.209**, [#12660](https://github.com/sveltejs/svelte/pull/12660)) +- `` is now unnecessary in runes mode and therefore is deprecated (**5.0.0-next.203/217**, [#12646](https://github.com/sveltejs/svelte/pull/12646) and [#12694](https://github.com/sveltejs/svelte/pull/12694)) +- `:global` is now allowed in more places - making it easier to use in `