feat: add compiler error when encountering a $-prefixed store value outside a `.svelte` file (#12799)

* feat: add compiler error when encountering a $-prefixed store value outside a .svelte file

* add fromState/toState APIs

* another test, update types

* rename fromState to toStore, and toState to fromStore

* docs

* add docs

* separate client/server entry points for svelte/store

.changeset/curvy-papayas-pretend.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+feat: add compiler error when encountering a $-prefixed store value outside a .svelte file

packages/svelte/messages/compile-errors/script.md

@@ -149,3 +149,9 @@
 ## store_invalid_subscription
 
 > Cannot reference store value inside `<script context="module">`
+
+## store_invalid_subscription_module
+
+> Cannot reference store value outside a `.svelte` file
+
+Using a `$` prefix to refer to the value of a store is only possible inside `.svelte` files, where Svelte can automatically create subscriptions when a component is mounted and unsubscribe when the component is unmounted. Consider migrating to runes instead.

packages/svelte/package.json

@@ -76,7 +76,8 @@
     },
     "./store": {
       "types": "./types/index.d.ts",
-      "default": "./src/store/index.js"
+      "browser": "./src/store/index-client.js",
+      "default": "./src/store/index-server.js"
     },
     "./transition": {
       "types": "./types/index.d.ts",

packages/svelte/src/compiler/errors.js

@@ -415,6 +415,15 @@ export function store_invalid_subscription(node) {
 	e(node, "store_invalid_subscription", "Cannot reference store value inside `<script context=\"module\">`");
 }
 
+/**
+ * Cannot reference store value outside a `.svelte` file
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function store_invalid_subscription_module(node) {
+	e(node, "store_invalid_subscription_module", "Cannot reference store value outside a `.svelte` file");
+}
+
 /**
  * Declaration cannot be empty
  * @param {null | number | NodeLike} node

packages/svelte/src/compiler/phases/2-analyze/index.js

@@ -219,6 +219,12 @@ export function analyze_module(ast, options) {
 		if (name === '$' || name[1] === '$') {
 			e.global_reference_invalid(references[0].node, name);
 		}
+
+		const binding = scope.get(name.slice(1));
+
+		if (binding !== null) {
+			e.store_invalid_subscription_module(references[0].node);
+		}
 	}
 
 	walk(

packages/svelte/src/motion/spring.js

@@ -1,7 +1,7 @@
 /** @import { Task } from '#client' */
 /** @import { SpringOpts, SpringUpdateOpts, TickContext } from './private.js' */
 /** @import { Spring } from './public.js' */
-import { writable } from '../store/index.js';
+import { writable } from '../store/shared/index.js';
 import { loop } from '../internal/client/loop.js';
 import { raf } from '../internal/client/timing.js';
 import { is_date } from './utils.js';

packages/svelte/src/motion/tweened.js

@@ -1,7 +1,7 @@
 /** @import { Task } from '../internal/client/types' */
 /** @import { Tweened } from './public' */
 /** @import { TweenedOptions } from './private' */
-import { writable } from '../store/index.js';
+import { writable } from '../store/shared/index.js';
 import { raf } from '../internal/client/timing.js';
 import { loop } from '../internal/client/loop.js';
 import { linear } from '../easing/index.js';

packages/svelte/src/store/index-client.js

@@ -0,0 +1,165 @@
+/** @import { Readable, Writable } from './public.js' */
+import { noop } from '../internal/shared/utils.js';
+import {
+	effect_root,
+	effect_tracking,
+	render_effect
+} from '../internal/client/reactivity/effects.js';
+import { source } from '../internal/client/reactivity/sources.js';
+import { get as get_source, tick } from '../internal/client/runtime.js';
+import { increment } from '../reactivity/utils.js';
+import { get, writable } from './shared/index.js';
+
+export { derived, get, readable, readonly, writable } from './shared/index.js';
+
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @param {(v: V) => void} set
+ * @returns {Writable<V>}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @returns {Readable<V>}
+ */
+/**
+ * Create a store from a function that returns state, and (to make a writable store), an
+ * optional second function that sets state.
+ *
+ * ```ts
+ * import { toStore } from 'svelte/store';
+ *
+ * let count = $state(0);
+ *
+ * const store = toStore(() => count, (v) => (count = v));
+ * ```
+ * @template V
+ * @param {() => V} get
+ * @param {(v: V) => void} [set]
+ * @returns {Writable<V> | Readable<V>}
+ */
+export function toStore(get, set) {
+	const store = writable(get(), (set) => {
+		let ran = false;
+
+		// TODO do we need a different implementation on the server?
+		const teardown = effect_root(() => {
+			render_effect(() => {
+				const value = get();
+				if (ran) set(value);
+			});
+		});
+
+		ran = true;
+
+		return teardown;
+	});
+
+	if (set) {
+		return {
+			set,
+			update: (fn) => set(fn(get())),
+			subscribe: store.subscribe
+		};
+	}
+
+	return {
+		subscribe: store.subscribe
+	};
+}
+
+/**
+ * @template V
+ * @overload
+ * @param {Writable<V>} store
+ * @returns {{ current: V }}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {Readable<V>} store
+ * @returns {{ readonly current: V }}
+ */
+/**
+ * Convert a store to an object with a reactive `current` property. If `store`
+ * is a readable store, `current` will be a readonly property.
+ *
+ * ```ts
+ * import { fromStore, get, writable } from 'svelte/store';
+ *
+ * const store = writable(0);
+ *
+ * const count = fromStore(store);
+ *
+ * count.current; // 0;
+ * store.set(1);
+ * count.current; // 1
+ *
+ * count.current += 1;
+ * get(store); // 2
+ * ```
+ * @template V
+ * @param {Writable<V> | Readable<V>} store
+ */
+export function fromStore(store) {
+	let value = /** @type {V} */ (undefined);
+	let version = source(0);
+	let subscribers = 0;
+
+	let unsubscribe = noop;
+
+	function current() {
+		if (effect_tracking()) {
+			get_source(version);
+
+			render_effect(() => {
+				if (subscribers === 0) {
+					let ran = false;
+
+					unsubscribe = store.subscribe((v) => {
+						value = v;
+						if (ran) increment(version);
+					});
+
+					ran = true;
+				}
+
+				subscribers += 1;
+
+				return () => {
+					subscribers -= 1;
+
+					tick().then(() => {
+						if (subscribers === 0) {
+							unsubscribe();
+						}
+					});
+				};
+			});
+
+			return value;
+		}
+
+		return get(store);
+	}
+
+	if ('set' in store) {
+		return {
+			get current() {
+				return current();
+			},
+			set current(v) {
+				store.set(v);
+			}
+		};
+	}
+
+	return {
+		get current() {
+			return current();
+		}
+	};
+}

packages/svelte/src/store/index-server.js

@@ -0,0 +1,101 @@
+/** @import { Readable, Writable } from './public.js' */
+import { get, writable } from './shared/index.js';
+
+export { derived, get, readable, readonly, writable } from './shared/index.js';
+
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @param {(v: V) => void} set
+ * @returns {Writable<V>}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @returns {Readable<V>}
+ */
+/**
+ * Create a store from a function that returns state, and (to make a writable store), an
+ * optional second function that sets state.
+ *
+ * ```ts
+ * import { toStore } from 'svelte/store';
+ *
+ * let count = $state(0);
+ *
+ * const store = toStore(() => count, (v) => (count = v));
+ * ```
+ * @template V
+ * @param {() => V} get
+ * @param {(v: V) => void} [set]
+ * @returns {Writable<V> | Readable<V>}
+ */
+export function toStore(get, set) {
+	const store = writable(get());
+
+	if (set) {
+		return {
+			set,
+			update: (fn) => set(fn(get())),
+			subscribe: store.subscribe
+		};
+	}
+
+	return {
+		subscribe: store.subscribe
+	};
+}
+
+/**
+ * @template V
+ * @overload
+ * @param {Writable<V>} store
+ * @returns {{ current: V }}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {Readable<V>} store
+ * @returns {{ readonly current: V }}
+ */
+/**
+ * Convert a store to an object with a reactive `current` property. If `store`
+ * is a readable store, `current` will be a readonly property.
+ *
+ * ```ts
+ * import { fromStore, get, writable } from 'svelte/store';
+ *
+ * const store = writable(0);
+ *
+ * const count = fromStore(store);
+ *
+ * count.current; // 0;
+ * store.set(1);
+ * count.current; // 1
+ *
+ * count.current += 1;
+ * get(store); // 2
+ * ```
+ * @template V
+ * @param {Writable<V> | Readable<V>} store
+ */
+export function fromStore(store) {
+	if ('set' in store) {
+		return {
+			get current() {
+				return get(store);
+			},
+			set current(v) {
+				store.set(v);
+			}
+		};
+	}
+
+	return {
+		get current() {
+			return get(store);
+		}
+	};
+}

packages/svelte/src/store/public.d.ts

@@ -48,4 +48,4 @@ interface Writable<T> extends Readable<T> {
 
 export { Readable, StartStopNotifier, Subscriber, Unsubscriber, Updater, Writable };
 
-export * from './index.js';
+export * from './index-client.js';

packages/svelte/src/store/shared/index.js

@@ -1,8 +1,8 @@
-/** @import { Readable, StartStopNotifier, Subscriber, Unsubscriber, Updater, Writable } from './public' */
-/** @import { Stores, StoresValues, SubscribeInvalidateTuple } from './private' */
-import { noop, run_all } from '../internal/shared/utils.js';
-import { safe_not_equal } from '../internal/client/reactivity/equality.js';
-import { subscribe_to_store } from './utils.js';
+/** @import { Readable, StartStopNotifier, Subscriber, Unsubscriber, Updater, Writable } from '../public.js' */
+/** @import { Stores, StoresValues, SubscribeInvalidateTuple } from '../private.js' */
+import { noop, run_all } from '../../internal/shared/utils.js';
+import { safe_not_equal } from '../../internal/client/reactivity/equality.js';
+import { subscribe_to_store } from '../utils.js';
 
 /**
  * @type {Array<SubscribeInvalidateTuple<any> | any>}

packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/_config.js

@@ -0,0 +1,8 @@
+import { test } from '../../test';
+
+export default test({
+	error: {
+		code: 'store_invalid_subscription_module',
+		message: 'Cannot reference store value outside a `.svelte` file'
+	}
+});

packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/main.svelte.js

@@ -0,0 +1,3 @@
+import { store } from 'somewhere';
+
+console.log($store);

packages/svelte/tests/store/test.ts

@@ -1,5 +1,17 @@
 import { describe, it, assert } from 'vitest';
-import { readable, writable, derived, get, readonly, type Readable } from 'svelte/store';
+import {
+	readable,
+	writable,
+	derived,
+	get,
+	readonly,
+	toStore,
+	type Readable,
+	fromStore
+} from 'svelte/store';
+import { source, set } from '../../src/internal/client/reactivity/sources';
+import * as $ from '../../src/internal/client/runtime';
+import { effect_root, render_effect } from 'svelte/internal/client';
 
 describe('writable', () => {
 	it('creates a writable store', () => {
@@ -574,3 +586,97 @@ describe('readonly', () => {
 		assert.throws(() => readableStore.set(3));
 	});
 });
+
+describe('toStore', () => {
+	it('creates a readable store from state', () => {
+		const count = source(0);
+
+		const store = toStore(() => $.get(count));
+
+		const log: number[] = [];
+
+		const unsubscribe = store.subscribe((value) => {
+			log.push(value);
+		});
+
+		assert.deepEqual(log, [0]);
+
+		set(count, 1);
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1]);
+
+		unsubscribe();
+	});
+
+	it('creates a writable store from state', () => {
+		const count = source(0);
+
+		const store = toStore(
+			() => $.get(count),
+			(v) => set(count, v)
+		);
+
+		const log: number[] = [];
+
+		const unsubscribe = store.subscribe((value) => {
+			log.push(value);
+		});
+
+		assert.deepEqual(log, [0]);
+
+		set(count, 1);
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1]);
+
+		store.set(2);
+		assert.equal($.get(count), 2);
+
+		unsubscribe();
+	});
+});
+
+describe('fromStore', () => {
+	it('creates state from a writable store', () => {
+		const store = writable(0);
+
+		const count = fromStore(store);
+
+		assert.equal(count.current, 0);
+
+		const log: number[] = [];
+
+		const teardown = effect_root(() => {
+			render_effect(() => {
+				log.push(count.current);
+			});
+		});
+
+		assert.deepEqual(log, [0]);
+
+		store.set(1);
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1]);
+
+		count.current = 2;
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1, 2]);
+
+		assert.equal(get(store), 2);
+
+		teardown();
+	});
+
+	it('creates state from a readable store', () => {
+		const store = readable(0);
+
+		const count = fromStore(store);
+
+		assert.equal(count.current, 0);
+
+		assert.throws(
+			// @ts-expect-error property is readonly
+			() => (count.current += 1),
+			'Cannot set property current of #<Object> which has only a getter'
+		);
+	});
+});

packages/svelte/types/index.d.ts

@@ -2306,6 +2306,17 @@ declare module 'svelte/store' {
 		 */
 		update(this: void, updater: Updater<T>): void;
 	}
+	export function toStore<V>(get: () => V, set: (v: V) => void): Writable<V>;
+
+	export function toStore<V>(get: () => V): Readable<V>;
+
+	export function fromStore<V>(store: Writable<V>): {
+		current: V;
+	};
+
+	export function fromStore<V>(store: Readable<V>): {
+		readonly current: V;
+	};
 	/**
 	 * Creates a `Readable` store that allows reading by subscription.
 	 *

sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md

@@ -192,6 +192,47 @@ const result = render(App, {
 
 If the `css` compiler option was set to `'injected'`, `<style>` elements will be included in the `head`.
 
+## `svelte/store`
+
+In addition to the existing store-related imports such as `writable`, `svelte/store` gains two new functions: `fromStore` and `toStore`. These allow you to easily use stores and rune-based state interchangeably, even outside `.svelte` files.
+
+### `fromStore`
+
+Takes a store and turns it into an object with a reactive (and readonly, if the store is not [writable](https://svelte.dev/docs/svelte-store#writable)) `current` property.
+
+```js
+import { fromStore, get, writable } from 'svelte/store';
+
+const store = writable(0);
+
+const count = fromStore(store);
+
+count.current; // 0;
+store.set(1);
+count.current; // 1
+
+count.current += 1;
+get(store); // 2
+```
+
+### `toStore`
+
+Creates a store from a function that returns reactive state (and, optionally, a second function that sets the state):
+
+```js
+import { toStore } from 'svelte/store';
+
+let count = $state(0);
+
+const store = toStore(
+	() => count,
+	(v) => (count = v)
+);
+
+store.set(1);
+count; // 1
+```
+
 ## `svelte/elements`
 
 Svelte provides built-in [DOM types](https://github.com/sveltejs/svelte/blob/master/packages/svelte/elements.d.ts). A common use case for DOM types is forwarding props to an HTML element. To properly type your props and get full intellisense, your props interface should extend the attributes type for your HTML element: