docs: address $effect feedback

[benmccann]

We've seen that $effect is being widely / wildly overused as Svelte 5 is adopted. This PR doesn't change the contents of the $effect docs much, but hopefully makes it easier to notice and retain some key pieces of information.

This makes a few changes:

• moves $effect down below $props in the sidebar. This sidebar seems to be sorted by order of importance, so we can reorder to signal that $effect should be used less than $props
• remove sentence about how Svelte uses effects internally. It's not important for helping understand how to use an effect
• add a note regarding when effects run as this is the other thing users are frequently encountering difficulty with. Moved this section down a bit both because it seems to make sense to show an example first and we don't want two notes in close succession
• moved down details about running in a microtask and being batched as these seem like more technical details that are better introduced a bit later

[changeset-bot]

⚠️ No Changeset found

Latest commit: e6fc4e2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-svelte-15107-svelte.vercel.app/

[github-actions]

Playground

pnpm add https://pkg.pr.new/svelte@15107

[trueadm]

Do we need a section to say that effects don't run on the server, and also they don't run in places where you need an active effect already, like an event listener or module instance?

[dummdidumm]

These are good changes! I'm not too sure about the ordering change in the side bar but I don't mind either way.

they don't run in places where you need an active effect already

Do you mean that they need an effect parent. That is already stated in the docs pretty far up.

I also think we should add something along the line of @paoloricciuti's recent "state in a derived" example to the "when not to use effects" section

[max-got]

imo to prevent the overuse of $effect the docs/Tutorial should have examples, that showcase common alternatives where people would use $effect otherwise. the docs should have best practice examples

[sacrosanctic]

Should have a list of all the places where svelte has encouraged the use of $effect

• in use:action
• it being equivalent to onMount

[sacrosanctic]

If an API is documented, it's generally assumed it's available for use. So the first line should include a warning explicitly stating that it should not be used, rather than beginning with a standard paragraph explaining its functionality.

[benmccann]

in places where you need an active effect already, like an event listener or module instance?

Is this an exhaustive list? If not, how would users understand where you need an active effect?

Do you mean that they need an effect parent. That is already stated in the docs pretty far up.

The term "parent effect" appears three times, but is never defined. Is a parent/child effects when you do something like $effect(() => { $effect(() => {}) })? Why/when would you do that?

I also think we should add something along the line of @paoloricciuti's recent "state in a derived" example to the "when not to use effects" section

Yeah, that makes sense unless we end up adding $state.link, but could probably be its own PR as it seems like a sizable update by itself.

Should have a list of all the places where svelte has encouraged the use of $effect
in use:action
equivalent to onMount

The use: docs mention this, which I think is a good place to put it. I'll update the onMount docs as well. (side note, onMount is equivalent to $effect(() => { untrack(fn) })`` rather than just $effect`)

If an API is documented, it's generally assumed it's available for use. So the first line should include a warning explicitly stating that it should not be used, rather than beginning with a standard paragraph explaining its functionality.

It is available for use. It's just important to use it as intended. The lightbulb callout has been moved up two paragraphs and now is right at the beginning, so I think it will be pretty prominent

[Ocean-OS]

in places where you need an active effect already, like an event listener or module instance?

Is this an exhaustive list? If not, how would users understand where you need an active effect?

That is the use case for $effect.active, but for now we could just say something like "if the code isn't executed when a component is running, you can't use an $effect."

Do you mean that they need an effect parent. That is already stated in the docs pretty far up.

The term "parent effect" appears three times, but is never defined. Is a parent/child effects when you do something like $effect(() => { $effect(() => {}) })? Why/when would you do that?

I'm pretty sure "parent effect" refers to $effect.root.

[trueadm]

I'm pretty sure "parent effect" refers to $effect.root.

The effect root can be the parent bit so can other $effect and $effect.pres. In fact internally Svelte creates lots of different types of effect for things like if blocks and each blocks. These too can be parents.