Note to Myself: Non-Obvious Details About Svelte 5 Runes

[newsve]

These is a collection of non-obvious details about Svelte 5 Runes, they are quite important when working with Runes and are scattered across the docs, GitHub issues/discussions and Reddit or just my own learnings. I update this list from time to time and you are welcome to contribute. You should know the very basics of Runes before reading this list.

1. $derived: The use of $derived and $derived.by is quite restricted since it can only be used as a variable declaration initializer or a class field; instead you can just use a function, e.g. () => someRuneState, it works everywhere, often requires less mental overhead and it is way less verbose; do not forget to call the function when using, contrary to $derived; still, $derived can be quite handy, in particular as variable declaration initializer in components where I still use it
2. Rune in store interoperability: Runes do not work in the old derived store (so the one without $), Runes within do not trigger updates; so old derived stores need to to be migrated as well (besides, you can't import derived anymore once in Rune mode using the new $derived, except you rename the old derived import)
3. Store in Rune interoperability: Contrary to above, stores work within Runes and do trigger updates in $derived, $derived.by, $effect and within a called function (1); outside of components use the fromStore function
4. Right order when migrating to Runes: Because of the prior two points, you should always migrate bottom-up and not top-down; this way, you can migrate in much smaller steps and keep the app and every commit still working; if you migrate top-down, you probably need to migrate many components and other files at once to keep every commit working which is just much harder and more error-prone
5. When to rename .ts files: While you need to rename .ts files to .svelte.ts when you use Runes, you do not need to do so when importing a function which contains Runes, e.g., count (a $state Rune) or derivedCount (a function, not a $derived Rune) from count.svelte.js can be imported to anotherFile.ts and used there; so you need to rename only when Runes are used explicitely
6. When to use object Runes: You can't reassign $state once exported if it contains primitives, you can work-around by using an object; defaulting to objects might seem over-eager and verbose, on the other side, one decision less every time you use them and you can add actions right away, so it might be good to default to objects outside of components since then, you would need to import them anyway; I am not yet decided if it is good to use also a default property key, e.g. .value
7. Spring API: The spring API, which is mainly used with some state, is deprecated and replaced by the new Spring class, check the docs but also this PR for more detailed docs, e.g., Spring.of is a handy way to create a derived Spring without the need of the need of $derived
8. $state as class fields: $state() as class fields turns them into private fields with auto-generated getters and setters, and, e.g., $state.snapshot() uses .toJSON() as part of its functionality, which can’t see private fields; so, you might run into hard-to-detect bugs, more in this Reddit post; this might also affect $derived, see also again (1)
9. VS Code Legaxy/Rune mode indicator: The Svelte plugin for VS Code shows above every .svelte file if the file is in Legacy or Rune mode BUT be aware that it still shows Legacy mode when neither legacy nor Rune APIs were used; this can be sometimes confusing when you migrate old files to Rune mode and wonder why it still shows as legacy

[jdvlpr]

I'm also discovering these paradigms as I update from Svelte 4 to 5 and search the new docs. It's helpful to have them in one place, thanks.

For number 2, I think it works the opposite way though, is that correct? E.g. an update to a store inside a $derived rune triggers an update?

[brunnerh]

For number 2, I think it works the opposite way though, is that correct? E.g. an update to a store inside a $derived rune triggers an update?

Correct.

Outside of components, where the $-syntax for stores cannot be used, there is a fromStore function that can be used (example).

[newsve]

Yes! I was just testing this myself and came back to update my post and saw your reply! Yes, in this direction they do work fortunately. 🙂

Edit: So, the initial post is updated and includes also the fromStore feature!