Registry / storage / ember-tracked-local-storage

ember-tracked-local-storage

library2.0.1jsnpmunverified

ember-tracked-local-storage is an Ember addon that synchronizes tracked properties with browser localStorage using Glimmer tracking, so mutations to stored values automatically trigger template re-renders. Version 2.0.1 is the latest stable release, requiring Ember.js 4.12+ and Node 18+. It uses the @trackedInLocalStorage decorator to wrap localStorage values and integrates with Ember's autotracking ecosystem. Unlike manual read/write patterns, this addon eliminates boilerplate and ensures reactivity without extra lifecycle hooks. Released under the adopted-ember-addons org with MIT license.

storage

npm install ember-tracked-local-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EMBER-TRACKED-LOCA

ember-tracked-local-storage

storagejavascriptv2.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

trackedInLocalStorage

✓ import { trackedInLocalStorage } from 'ember-tracked-local-storage';

✗ import trackedInLocalStorage from 'ember-tracked-local-storage';

This is a named export. Default import is incorrect. The addon only exports this single decorated.

default

✓ import { trackedInLocalStorage } from 'ember-tracked-local-storage';

✗ import trackedInLocalStorage from 'ember-tracked-local-storage';

Default export does not exist. Always use named import syntax.

EmberTrackedLocalStorage

✓ import { trackedInLocalStorage } from 'ember-tracked-local-storage';

✗ import EmberTrackedLocalStorage from 'ember-tracked-local-storage';

Some users mistakenly expect a default class export; the addon only provides the decorator function.

Creates a tracked property synced with localStorage; changing the value updates the template automatically.

import Component from '@glimmer/component'; import { trackedInLocalStorage } from 'ember-tracked-local-storage'; export default class MyComponent extends Component { @trackedInLocalStorage() theme = 'light'; get display() { return `Current theme: ${this.theme}`; } toggleTheme() { this.theme = this.theme === 'light' ? 'dark' : 'light'; } }

Debug

Known issues

breakingRequires Ember.js 4.12+; older Ember versions (<4.12) are not supported.

fix

Upgrade to Ember 4.12 or later, or use v1.x (which may have different constraints).

affects: >=2.0.0

breakingNode.js 18+ is required; Node 16 and below are not supported.

fix

Upgrade to Node.js 18 or later.

affects: >=2.0.0

deprecatedThe deprecated @ember/optional-features feature flag is no longer needed, but older Ember versions may still rely on it.

fix

Update to v2.x and remove any optional feature configurations.

affects: >=1.0.0 <2.0.0

gotchaValues stored in localStorage are serialized to strings; objects and arrays will be JSON.stringify'd automatically.

fix

Use only primitive-like values or ensure JSON round-trip compatibility. Do not store functions or symbols.

affects: >=1.0.0

gotchaThe decorator uses the property name as the localStorage key; collisions can occur if two components use the same key.

fix

Pass a unique key argument to @trackedInLocalStorage('myCustomKey') to avoid collisions.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'localStorage')

Using the decorator in a non-browser environment (e.g., FastBoot or testing without localStorage mock)

fix

Wrap usage with a guard: if (typeof localStorage !== 'undefined') { ... }

Error: You attempted to set a property on a component that is not tracked

Decorator not applied correctly (missing parentheses or import misnamed)

fix

Ensure import: import { trackedInLocalStorage } from 'ember-tracked-local-storage'; and use @trackedInLocalStorage() initialValue;

Assertion Failed: You cannot use @trackedInLocalStorage on a non-tracking-enabled component

Component does not extend from @glimmer/component or Ember's Glimmer component class

fix

Extend from Component (import Component from '@glimmer/component') or an Ember native class with @tracked.

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

ember-sourceoptionalRuntime peer dependency required for Glimmer component and autotracking support

Agent activity

22 hits · last 30 days

node

Amazon

Resources

githubssh://git@github.com/adopted-ember-addons/ember-tracked-local-storage ↗

packageember-tracked-local-storage ↗

homepagehttps://github.com/adopted-ember-addons/ember-tracked-local-storage#readme ↗