From cd11379711f8136bbf3420fd0a0654384323edee Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 15 May 2025 09:31:40 -0400 Subject: [PATCH 1/5] clarify when attachments re-run --- documentation/docs/03-template-syntax/09-@attach.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/docs/03-template-syntax/09-@attach.md b/documentation/docs/03-template-syntax/09-@attach.md index 2df0882e34d4..cd1483a4b647 100644 --- a/documentation/docs/03-template-syntax/09-@attach.md +++ b/documentation/docs/03-template-syntax/09-@attach.md @@ -2,7 +2,9 @@ title: {@attach ...} --- -Attachments are functions that run when an element is mounted to the DOM. Optionally, they can return a function that is called when the element is later removed from the DOM. +Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates. + +Optionally, they can return a function that is called when the element is later removed from the DOM. > [!NOTE] > Attachments are available in Svelte 5.29 and newer. @@ -55,7 +57,7 @@ A useful pattern is for a function, such as `tooltip` in this example, to _retur ``` -Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. +Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read _inside_ the attachment function when it first runs. ## Inline attachments From edb5774dad0fc4f1e4876a613be7eefd18c568cc Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 15 May 2025 09:32:42 -0400 Subject: [PATCH 2/5] Update documentation/docs/03-template-syntax/09-@attach.md --- documentation/docs/03-template-syntax/09-@attach.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/03-template-syntax/09-@attach.md b/documentation/docs/03-template-syntax/09-@attach.md index cd1483a4b647..9901541160b5 100644 --- a/documentation/docs/03-template-syntax/09-@attach.md +++ b/documentation/docs/03-template-syntax/09-@attach.md @@ -4,7 +4,7 @@ title: {@attach ...} Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates. -Optionally, they can return a function that is called when the element is later removed from the DOM. +Optionally, they can return a function that is called before the attachment re-runs, or when the element is later removed from the DOM. > [!NOTE] > Attachments are available in Svelte 5.29 and newer. From e4ee271391b53b1ca42dc6e82c97b6ec362a8004 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 15 May 2025 09:34:41 -0400 Subject: [PATCH 3/5] Update documentation/docs/03-template-syntax/09-@attach.md --- documentation/docs/03-template-syntax/09-@attach.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/03-template-syntax/09-@attach.md b/documentation/docs/03-template-syntax/09-@attach.md index 9901541160b5..f79924330461 100644 --- a/documentation/docs/03-template-syntax/09-@attach.md +++ b/documentation/docs/03-template-syntax/09-@attach.md @@ -4,7 +4,7 @@ title: {@attach ...} Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates. -Optionally, they can return a function that is called before the attachment re-runs, or when the element is later removed from the DOM. +Optionally, they can return a function that is called before the attachment re-runs, or after the element is later removed from the DOM. > [!NOTE] > Attachments are available in Svelte 5.29 and newer. From 49c8582770c787b5f8136aab0c6ed5d523ba1f52 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Mon, 19 May 2025 16:11:55 -0400 Subject: [PATCH 4/5] update docs --- .../docs/03-template-syntax/09-@attach.md | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/documentation/docs/03-template-syntax/09-@attach.md b/documentation/docs/03-template-syntax/09-@attach.md index f79924330461..2a856d45cefd 100644 --- a/documentation/docs/03-template-syntax/09-@attach.md +++ b/documentation/docs/03-template-syntax/09-@attach.md @@ -57,7 +57,7 @@ A useful pattern is for a function, such as `tooltip` in this example, to _retur ``` -Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read _inside_ the attachment function when it first runs. +Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read _inside_ the attachment function when it first runs. (If this isn't what you want, see [Controlling when attachments re-run](#Controlling-when-attachments-re-run).) ## Inline attachments @@ -128,6 +128,33 @@ This allows you to create _wrapper components_ that augment elements ([demo](/pl ``` +## Controlling when attachments re-run + +Attachments, unlike [actions](use), are fully reactive: `{@attach foo(bar)}` will re-run on changes to `foo` _or_ `bar` (or any state read inside `foo`): + +```js +function foo(bar) { + return (node) => { + veryExpensiveSetupWork(node); + update(node, bar); + }; +} +``` + +In the rare case that this is a problem (for example, if `foo` does expensive and unavoidable setup work) consider passing the data inside a function and reading it in a child effect: + +```js +function foo(+++getBar+++) { + return (node) => { + veryExpensiveSetupWork(node); + ++++ $effect(() => { + update(node, getBar()); + });+++ + } +} +``` + ## Creating attachments programmatically To add attachments to an object that will be spread onto a component or element, use [`createAttachmentKey`](svelte-attachments#createAttachmentKey). From 398171b2eb0fa03281f0fe28ac694c5e84e1d78f Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Mon, 19 May 2025 16:28:35 -0400 Subject: [PATCH 5/5] fix --- documentation/docs/03-template-syntax/09-@attach.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation/docs/03-template-syntax/09-@attach.md b/documentation/docs/03-template-syntax/09-@attach.md index 2a856d45cefd..3644cbc8e8db 100644 --- a/documentation/docs/03-template-syntax/09-@attach.md +++ b/documentation/docs/03-template-syntax/09-@attach.md @@ -133,6 +133,7 @@ This allows you to create _wrapper components_ that augment elements ([demo](/pl Attachments, unlike [actions](use), are fully reactive: `{@attach foo(bar)}` will re-run on changes to `foo` _or_ `bar` (or any state read inside `foo`): ```js +// @errors: 7006 2304 2552 function foo(bar) { return (node) => { veryExpensiveSetupWork(node); @@ -144,6 +145,7 @@ function foo(bar) { In the rare case that this is a problem (for example, if `foo` does expensive and unavoidable setup work) consider passing the data inside a function and reading it in a child effect: ```js +// @errors: 7006 2304 2552 function foo(+++getBar+++) { return (node) => { veryExpensiveSetupWork(node);