vue-ls

library4.2.0jsnpmunverified

Vue-ls is a Vue.js plugin designed to simplify interactions with client-side storage mechanisms. It provides a consistent API to manage `localStorage`, `sessionStorage`, and an optional in-memory fallback, making it highly flexible for different use cases. The current stable version, 4.2.0, fully supports Vue 3 applications, while maintaining compatibility with Vue 1.x and 2.x, as indicated by its badges and release history (v4.0.0 introduced Vue 3 support). The library offers a reactive approach to storage, allowing developers to set, get, remove items, and even watch for changes on specific keys, which is a significant differentiator compared to the native Web Storage API. Its plugin architecture integrates seamlessly into Vue applications via `Vue.use()`, exposing storage methods directly on the Vue instance or globally. The project has a moderate release cadence, with continuous improvements and maintenance releases following major updates.

web-framework

npm install vue-ls

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-LS

vue-ls

web-frameworkjavascriptv4.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Storage

✓ import Storage from 'vue-ls';

✗ import { Storage } from 'vue-ls';

The library is primarily consumed via a default import which provides the plugin object to `Vue.use()`.

$ls

✓ this.$ls.set('key', 'value');

✗ Storage.set('key', 'value');

After `Vue.use(Storage)`, the storage instance is available as `$ls` on the Vue instance or `Vue.ls` globally. Direct use of the imported `Storage` object for operations is incorrect.

Vue.use

✓ import Vue from 'vue'; import Storage from 'vue-ls'; Vue.use(Storage, options);

✗ import { createApp } from 'vue'; import Storage from 'vue-ls'; const app = createApp(App); app.use(Storage, options);

For Vue 3, `app.use(Storage, options)` is the correct pattern, where `app` is the application instance returned by `createApp()`. The `Vue.use()` global method is deprecated in Vue 3.

This quickstart demonstrates how to install and use `vue-ls` within a Vue 3 application. It covers setting, retrieving, and removing items from local storage, including setting an expiry. It also showcases the unique `on` method for watching changes to a storage key and accessing the storage instance via `this.$ls`.

import { createApp } from 'vue'; import Storage from 'vue-ls'; const options = { namespace: 'my_app__', name: 'ls', storage: 'local' // Can be 'local', 'session', or 'memory' }; const App = { template: ` <div> <h1>Vue-ls Example</h1> <p>Current value of 'my_item': {{ myItem }}</p> <input v-model="inputValue" placeholder="Enter value"> <button @click="setItem">Set Item</button> <button @click="removeItem">Remove Item</button> <button @click="clearStorage">Clear All</button> </div> `, data() { return { inputValue: '', myItem: '' }; }, mounted() { // Initialize with a default or stored value this.myItem = this.$ls.get('my_item', 'default_value'); // Watch for changes to 'my_item' key (useful for cross-tab communication) this.$ls.on('my_item', (newValue, oldValue, url) => { console.log(`'my_item' changed from ${oldValue} to ${newValue} on ${url}`); this.myItem = newValue; }); }, methods: { setItem() { this.$ls.set('my_item', this.inputValue, 60 * 60 * 1000); // Set with 1-hour expiry this.myItem = this.inputValue; this.inputValue = ''; }, removeItem() { this.$ls.remove('my_item'); this.myItem = this.$ls.get('my_item', 'removed'); }, clearStorage() { this.$ls.clear(); this.myItem = this.$ls.get('my_item', 'cleared'); } }, beforeUnmount() { // Don't forget to unwatch if not needed anymore // this.$ls.off('my_item', callback); } }; const app = createApp(App); app.use(Storage, options); app.mount('#app');

Debug

Known issues

breakingVersion 4.0.0 introduced support for Vue 3. While the core API remains largely the same, Vue 3's plugin installation mechanism changed from `Vue.use()` to `app.use()`. Ensure you update your plugin registration accordingly for Vue 3 projects.

fix

For Vue 3, instantiate your app with `createApp()` and then call `app.use(Storage, options)`. For Vue 2, `Vue.use(Storage, options)` remains correct.

affects: >=4.0.0

gotchaBrowser storage (localStorage, sessionStorage) is synchronous and has size limitations (typically 5-10MB). Storing very large objects or performing frequent heavy read/write operations can block the main thread and degrade application performance.

fix

For large or complex data, consider alternatives like IndexedDB. For performance-critical updates, debounce or throttle storage operations. Only store essential, non-sensitive data in client-side storage.

affects: >=1.0.0

gotchaKeys stored in `localStorage` or `sessionStorage` are global to the origin. If multiple applications or components on the same domain use the same keys without a namespace, they can overwrite each other's data, leading to unexpected behavior. `vue-ls` provides a `namespace` option, but it's crucial to utilize it.

fix

Always configure a unique `namespace` option during plugin installation (e.g., `namespace: 'my_app_prefix__'`) to prevent key collisions with other scripts or applications on the same origin.

affects: >=1.0.0

gotchaThe `expire` parameter for `set()` provides a client-side expiration mechanism managed by `vue-ls`, not native `localStorage`. If `localStorage` is cleared by the user or the application's data structure changes, these expirations will not be respected unless the `vue-ls` plugin re-processes the stored data.

fix

Understand that expiry is a soft, client-side mechanism. Do not rely on it for critical security or data integrity. For robust expiry, implement server-side validation or more sophisticated client-side storage management if the data is highly sensitive or volatile.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: app.use is not a function

Attempting to use `Vue.use()` with a Vue 3 application instance directly instead of `app.use()`, or vice-versa.

fix

For Vue 3, ensure you use `const app = createApp(App); app.use(Storage, options);`. For Vue 2, use `Vue.use(Storage, options);`.

TypeError: Cannot read properties of undefined (reading 'set') OR TypeError: Vue.ls is undefined

`vue-ls` was not properly installed as a Vue plugin via `Vue.use()` or `app.use()`, or it is being accessed outside a Vue component's context where `$ls` is available, and `Vue.ls` hasn't been configured or exposed globally.

fix

Ensure `app.use(Storage, options)` (Vue 3) or `Vue.use(Storage, options)` (Vue 2) is called before the Vue application is mounted. When accessing outside a component, `Vue.ls` must be configured globally if using Vue 2, or you can import and use `Storage.useStorage(options).ls` directly in modules.

DOMException: Failed to execute 'setItem' on 'Storage': Setting the value of 'key' exceeded the quota.

The browser's storage quota for the origin (typically 5-10MB for `localStorage`) has been exceeded by trying to store too much data.

fix

Reduce the amount of data being stored in `localStorage`. Consider using `sessionStorage` for temporary data or `IndexedDB` for larger datasets. Implement a graceful fallback or alert the user when quota is exceeded.

Upgrade

Version history

4.2.0latest on npm

Audit

Dependencies

vuerequiredPeer dependency as it's a Vue plugin, compatible with Vue 1.x, 2.x, and 3.x.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/RobinCK/vue-ls ↗

packagehttps://www.npmjs.com/package/vue-ls ↗