Getting Started

Introduction

If your project requires using web storage (either localStorage or sessionStorage) to persist data, and you want the data to be retained after a page refresh while also automatically updating the view when the data changes, ew-responsive-store is the perfect solution.

It's about 4 KB gzipped and extremely easy to use. With just a single function call, you can make storage data reactive, which can be applied to any framework-based project, even native JavaScript projects. The library also includes comprehensive unit tests and type inference.

Installation

First, you need to install the ew-responsive-store package. You can install it using the following command:

1npm install ew-responsive-store
2# Or using pnpm
3pnpm add ew-responsive-store
4# Or using yarn
5yarn add ew-responsive-store

Framework Dependencies

Since v0.0.3, ew-responsive-store supports multiple frameworks. You only need to install the framework you're using:

1# For React
2npm install react
3
4# For Vue
5npm install @vue/reactivity
6
7# For Preact
8npm install preact
9
10# For Solid
11npm install solid-js
12
13# For Svelte
14npm install svelte
15
16# For Angular
17npm install @angular/core

Note: Framework dependencies are treated as external, so they won't be bundled with your application, keeping the library size minimal.

Environment and Dependency Notes

  • React 18+: The React adapter is built on useSyncExternalStore, and peerDependencies requires react >= 18. React 17 and earlier are not supported.
  • Avoid duplicate installs: Same-tab sync relies on a module-level registry. If multiple copies of ew-responsive-store are installed (multiple versions, a monorepo without hoisting, or a package manager that did not dedupe), the registry is split and components sharing the same key will not sync. Run npm dedupe / pnpm dedupe / yarn dedupe, or configure resolve.dedupe: ['ew-responsive-store'] in Vite.
  • Dynamic key cleanup: Framework adapters release the manager automatically on unmount. For manually created instances or non-component scenarios, call releaseStorageManager(key, storage); the instance is removed from the registry and destroyed in a microtask. When using Vue outside setup, wrap the call in effectScope() and call scope.stop() to release automatically. In Angular, call it within an injection context (component/service), otherwise release manually.

Framework-Specific Imports

Since v0.0.3, you should import from framework-specific entry points:

1// Vue
2import { useStorage } from 'ew-responsive-store/vue';
3
4// React
5import { useStorage } from 'ew-responsive-store/react';
6
7// Preact
8import { useStorage } from 'ew-responsive-store/preact';
9
10// Solid
11import { useStorage } from 'ew-responsive-store/solid';
12
13// Svelte
14import { useStorage } from 'ew-responsive-store/svelte';
15
16// Angular
17import { useStorage } from 'ew-responsive-store/angular';
18
19// Vanilla JS
20import { useStorage } from 'ew-responsive-store/vanilla';
21// or
22import { useStorage } from 'ew-responsive-store';

Basic Usage

The root entry of ew-responsive-store exports the vanilla JavaScript useStorage, along with StoreType, ParseStrType, the StorageManager APIs, and utilities such as parseStr, isValidJSON, and isStorageEnabled. The root useStorage turns localStorage / sessionStorage data into a reactive object; for Vue, React, and other frameworks, use their dedicated subpath entries.

Basic Values

You can use useStorage to create reactive basic values. For example, let's say you have a counter stored in localStorage:

1import { useStorage } from "ew-responsive-store/vue";
2
3// Initialize the count with a default value of 0
4const count = useStorage("count", 0);
5
6// Modify the count value
7count.value++; // count value becomes 1

Vue Template Code:

1<template>
2  <p>{{ count }}</p>
3  <button @click="count++">Click Me</button>
4</template>
5
6<script setup>
7import { useStorage } from "ew-responsive-store/vue";
8
9const count = useStorage("count", 0);
10</script>

At this point, the value of count is stored in the browser's session storage, and it is reactive, meaning it will persist even after the page refreshes and the view will update automatically when the value changes.

Object Values

You can also store reactive objects in a similar way:

1import { useStorage } from "ew-responsive-store/vue";
2
3// Initialize the userInfo object
4const userInfo = useStorage("user", { name: "eveningwater" });
5
6// Modify the userInfo object
7userInfo.value.name = "夕水"; // userInfo's name property becomes '夕水'

When you change the name property of userInfo, the view will automatically update, and the data will be saved in session storage.

Array Values

You can also store arrays, and they will be reactive as well:

1import { useStorage } from "ew-responsive-store/vue";
2
3// Initialize an array
4const countList = useStorage("countList", [1, 2, 3]);
5
6// Modify the array
7countList.value.push(4); // The array becomes [1, 2, 3, 4]

Using Outside setup (effectScope)

The Vue adapter releases the storage manager on unmount via onScopeDispose. When you call it outside setup or an effectScope (e.g. a module-level singleton, Pinia store initialization, or a utility function), there is no lifecycle to hook into, so create an explicit scope:

1import { effectScope } from 'vue'
2import { useStorage } from 'ew-responsive-store/vue'
3
4const scope = effectScope()
5
6// Called inside the scope, useStorage binds to it automatically
7const settings = scope.run(() => useStorage('settings', { theme: 'light' }))!
8
9settings.value.theme = 'dark'
10
11// Stop the scope when it is no longer needed; the manager is released automatically
12scope.stop()

Notes:

  • scope.stop() also stops watchers and reactive effects inside the scope; afterwards settings is no longer synced with storage.
  • If effectScope is not an option, release manually. The key and storage area must match the ones used at creation:
1import { releaseStorageManager, StoreType } from 'ew-responsive-store'
2
3releaseStorageManager('settings', StoreType.LOCAL)
  • Calling useStorage directly inside a component's setup needs no extra handling; unmount releases it automatically.

For more advanced usage and configuration options, check out the API Reference section.