Describe the problem

Issue with Runes Documentation

Using the runes in a component is documented nicely but when you go to replicate those patterns for importing runes the experience falls apart instantly and a new undocumented pattern has to be used.

State Example from Documentation

This is the $state example from the Svelte 5 runes docs: https://svelte.dev/playground/6b854f5d5fc2465ea5d9306d13f51b85?version=5.2.7

Importing with the Same Pattern

This is what happens when you take that example and try and define that state elsewhere and import it (even assuming you knew to call the file ".svelte.js"): https://svelte.dev/playground/61c1a5769d99478dac3be0206a7ced1f?version=5.2.7

Working Importing Runes Pattern

This is how you ACTUALLY have to import runes and (I had to discover this in Discord): https://svelte.dev/playground/d25142f533d844b080dd6eb756ac0ba3?version=5.2.7

Exampling using Stores

So, when imported, $state runes CANNOT hold a value themselves. This is counter to the example and also counter to how stores used to work: https://svelte.dev/playground/3ca44f7cac3841a688ecad512d3b87df?version=5.2.7

As you can see the stores example allows my store to hold the actual value and I don't need to do something different like add a "value" property.

To summarize

Magic:

Defining runes in a component
Defining stores in a component or importing them

Not Magic:

Importing a rune

Describe the proposed solution

Suggestion

I don't have a problem with having to do something different when I import runes, that's not what this is about. I'm sure the Svelte 5 devs have good reasons they work this way and I'm not here to judge. I tend to always define my state in separate files, so personally I will only have 1 pattern to contend with in my own apps.

I'm raising this issue so that the runes documentation can hopefully get an update to include the pattern needed when importing runes. Maybe a new section after $host called "importing" that just illustrates what I have shown above.

If this is somewhere in the documentation then I could not find it by searching. The only official thing I was given in Discord was a link to some tutorial section that didn't even have runes or $state in the name which isn't good for discoverability. Furthermore a tutorial should be a walkthrough of the documentation, not the other way around.

Alternatives considered

No response

Importance

would make my life easier

Additional Information

Coming from Svelte 4 and using stores extensively this was a departure and a bit of a roadblock for me. I would like other developers to be able to discover this pattern from the documentation and not from Discord like I had to.

sveltejs / svelte

Document Pattern for Importing Runes #14416