Reactive built-ins

Active contributors: Rich Harris, Simon H, Dominic Gannaway

Purpose

svelte/reactivity exports drop-in replacements for built-in JavaScript objects whose mutations participate in the reactivity engine. Reading a property of a SvelteMap inside a Reaction registers as a dependency; mutating it elsewhere triggers re-runs.

Public exports

From packages/svelte/src/reactivity/index-client.js and index-server.js:

Class	File	Mirrors
SvelteMap	packages/svelte/src/reactivity/map.js	Map
SvelteSet	packages/svelte/src/reactivity/set.js	Set
SvelteDate	packages/svelte/src/reactivity/date.js	Date
SvelteURL	packages/svelte/src/reactivity/url.js	URL
SvelteURLSearchParams	packages/svelte/src/reactivity/url-search-params.js	URLSearchParams
MediaQuery	packages/svelte/src/reactivity/media-query.js	window.matchMedia
createSubscriber	packages/svelte/src/reactivity/create-subscriber.js	(low-level subscription primitive)

svelte/reactivity/window (packages/svelte/src/reactivity/window/) exposes browser-only reactive globals: innerWidth, innerHeight, scrollX, scrollY, screenLeft, screenTop, online, devicePixelRatio, etc. These are class instances with a .current getter that subscribes to the underlying browser event (resize, scroll, online, change on a MediaQueryList).

How they're built

Every class follows the same recipe:

1. Wrap the underlying primitive (new Map(), new Date(), new URL(...), etc.) as the actual storage.
2. For each read method (e.g., Map.prototype.get, Map.prototype.has, Set.prototype.size), call into get(source) from internal/client/runtime.js so reads register a dependency.
3. For each mutation method (set, add, delete, clear, etc.), call set(source, ...) or increment(version_source) to mark dependents dirty.
4. Iteration methods (entries, keys, values, forEach, Symbol.iterator) consume a version source so additions/removals invalidate iterators.

createSubscriber

packages/svelte/src/reactivity/create-subscriber.js is the lower-level primitive used by MediaQuery, the window-state utilities, and the store interop in svelte/store#fromStore. Given a (update) => unsubscribe factory, it returns a subscribe() function that:

• When called from inside a Reaction, ensures the factory has been invoked at least once and registers a dependency on a hidden version source.
• When the surrounding effect tears down, unsubscribes if no other reactions depend on it.

This is what user-land libraries should use to wrap an external observable into something rune-friendly.

Tests

Each module ships its own unit tests:

• packages/svelte/src/reactivity/map.test.ts
• packages/svelte/src/reactivity/set.test.ts
• packages/svelte/src/reactivity/date.test.ts
• packages/svelte/src/reactivity/url.test.ts
• packages/svelte/src/reactivity/url-search-params.test.ts

Run via pnpm test reactivity (or with a more specific filter).

Server behaviour

The server entry (packages/svelte/src/reactivity/index-server.js) re-exports the same classes but their reactive plumbing is no-op (since there's no client-side runtime). On the server, SvelteMap behaves like a regular Map.

Key source files

File	Purpose
packages/svelte/src/reactivity/index-client.js	Browser entry — exports all classes.
packages/svelte/src/reactivity/create-subscriber.js	Low-level subscription helper.
packages/svelte/src/reactivity/map.js	SvelteMap (~6 KB).
packages/svelte/src/reactivity/set.js	SvelteSet (~5 KB).
packages/svelte/src/reactivity/date.js	SvelteDate (~3 KB).
packages/svelte/src/reactivity/url.js	SvelteURL (~5 KB).
packages/svelte/src/reactivity/url-search-params.js	SvelteURLSearchParams (~4 KB).
packages/svelte/src/reactivity/media-query.js	MediaQuery.
packages/svelte/src/reactivity/window/	Reactive window state (browser-only).

Entry points for modification

If you're adding a new reactive built-in, follow the existing pattern: create a class, hold a version Source, increment it on mutation and read it on access. Add a sibling .test.ts with the same name.