From 6eb1340953d61efc866a93c5781245eb407fe766 Mon Sep 17 00:00:00 2001
From: Todd Williams <toddsurfs@icloud.com>
Date: Fri, 21 Mar 2025 17:05:06 -0700
Subject: [PATCH 1/2] Improve documentation regarding .svelte.js and svelte.ts
 $state export rules

---
 .../01-introduction/04-svelte-js-files.md     | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/documentation/docs/01-introduction/04-svelte-js-files.md b/documentation/docs/01-introduction/04-svelte-js-files.md
index 0e05484299db..68dc7d9e4e1b 100644
--- a/documentation/docs/01-introduction/04-svelte-js-files.md
+++ b/documentation/docs/01-introduction/04-svelte-js-files.md
@@ -8,3 +8,25 @@ These behave like any other `.js` or `.ts` module, except that you can use runes
 
 > [!LEGACY]
 > This is a concept that didn't exist prior to Svelte 5
+
+### Sharing `$state` Across Modules
+
+When exporting reactive state from a module using `$state`, ensure it remains reactive and predictable by following one of these approaches:
+
+- **Export a function**: Return the `$state` value from a function to encapsulate and provide access to it.
+- **Export an object**: Use `$state` with an object and mutate its properties to trigger reactivity.
+
+Reassigning an exported `$state` variable (e.g., `count = 5`) in the module where it’s defined is not allowed, as it breaks reactivity tracking. Instead, choose one of these patterns:
+
+```javascript
+// Option 1: Export a function
+export function getCount() {
+  return $state(0);
+}
+
+// Option 2: Export an object and mutate properties
+export let state = $state({ count: 0 });
+// Later: state.count += 1; (valid mutation)
+```
+
+> [!NOTE] You cannot reassign an exported $state variable (e.g., count = 5) in its module. Either export a function returning the state or use an object and mutate its properties to maintain reactivity. See [Compiler Errors: state_invalid_export](https://svelte.dev/docs/svelte/compiler-errors#state_invalid_export) for details.

From 5d131b1144ea006a5f832b43c0c8c2601481d273 Mon Sep 17 00:00:00 2001
From: Todd Williams <toddsurfs@icloud.com>
Date: Fri, 21 Mar 2025 17:10:20 -0700
Subject: [PATCH 2/2] update docs with MDN JavaScript details

---
 documentation/docs/01-introduction/04-svelte-js-files.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/01-introduction/04-svelte-js-files.md b/documentation/docs/01-introduction/04-svelte-js-files.md
index 68dc7d9e4e1b..b8e1b3d06ff0 100644
--- a/documentation/docs/01-introduction/04-svelte-js-files.md
+++ b/documentation/docs/01-introduction/04-svelte-js-files.md
@@ -29,4 +29,4 @@ export let state = $state({ count: 0 });
 // Later: state.count += 1; (valid mutation)
 ```
 
-> [!NOTE] You cannot reassign an exported $state variable (e.g., count = 5) in its module. Either export a function returning the state or use an object and mutate its properties to maintain reactivity. See [Compiler Errors: state_invalid_export](https://svelte.dev/docs/svelte/compiler-errors#state_invalid_export) for details.
+> [!NOTE] You cannot reassign an exported $state variable (e.g., count = 5) in its module. Either export a function returning the state or use an object and mutate its properties to maintain reactivity. See [Compiler Errors: state_invalid_export](https://svelte.dev/docs/svelte/compiler-errors#state_invalid_export) for Svelte-specific details, and [MDN: JavaScript export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) for how JavaScript module bindings work.