Svelte's Legacy immutable={true} Optimization

Why it exists

Svelte's reactivity system needs to know when data changes to update the DOM. By default, it's cautious with objects and arrays, assuming they might be mutated internally, which can require more complex change detection. The immutable={true} option was created for Svelte 3/4 to let developers signal a stricter, more performant update model when they knew their data was immutable.

The mental model

Think of immutable={true} as a "trust mode" for the compiler. You tell Svelte, "Trust me, I will never change an object's properties directly. I will always replace the entire object with a new one." In return, Svelte uses a simple, fast reference check (oldValue === newValue) to see if the data has changed, skipping a slower inspection of its contents.

How it works

By adding <svelte:options immutable={true} /> to a component, you instruct the Svelte compiler to change its change-detection logic for that component's data. Instead of being conservative, the compiler generates code that only checks if a variable's reference has changed. An assignment like myObject.property = 'new value' won't be detected, as the reference to myObject remains the same. An assignment like myObject = { ...myObject, property: 'new value' } will be detected because it creates a new object with a new reference.

When to use it

This option was valuable in Svelte 3 and 4 for performance-critical components, especially when using state management libraries or patterns that enforce immutability (like Immer or Redux-style reducers). If you were already disciplined about creating new objects and arrays for every state change, enabling this gave you a performance boost by simplifying the compiler's output.

When not to use it

Do not use this in Svelte 5, as it is deprecated and non-functional in the default runes mode. In older versions, avoid it if your codebase relies on direct mutation, such as using array.push(), array.splice(), or assigning to object properties (obj.key = value). Using it in such cases is a primary footgun, leading to baffling bugs where your data model changes but the UI does not reflect it.

One canonical example

In a Svelte 4 component, if you update a user's name by mutating an object (users[0].name = 'New Name'), with immutable={true} enabled, the UI will not update. The correct, immutable way is to create a new array with a new user object: users = users.map(u => u.id === targetId ? { ...u, name: 'New Name' } : u). This creates a new array reference, which Svelte's fast check detects, triggering a UI update.