{"id":17287,"library":"lockr","title":"Lockr: LocalStorage Wrapper","description":"Lockr is an extremely lightweight JavaScript library (<2KB minified) designed to simplify interactions with the browser's `localStorage` API. It provides a Redis-like API for storing various data types, including strings, numbers, objects, and arrays, and offers set-like operations (e.g., `sadd`, `smembers`, `sismember`, `srem`). It is currently in a beta phase, with version 0.9.0-beta.2, indicating ongoing development. While no explicit release cadence is stated, the active development and beta tag suggest regular updates towards a stable release. Its primary differentiator is its automatic object serialization/deserialization and its distinct Redis-inspired API for managing collections, moving beyond the simple key-value string storage of native `localStorage` and offering a more feature-rich experience.","status":"active","version":"0.9.0-beta.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install lockr","lang":"bash","label":"npm"},{"cmd":"yarn add lockr","lang":"bash","label":"yarn"},{"cmd":"pnpm add lockr","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Lockr is typically used as a default export, providing a global-like API.","wrong":"import { Lockr } from 'lockr'","symbol":"Lockr","correct":"import Lockr from 'lockr'"},{"note":"For CommonJS environments, the entire API is exposed via the module export.","symbol":"Lockr (CommonJS)","correct":"const Lockr = require('lockr')"},{"note":"Can also be imported as a namespace, though direct default import is more common.","symbol":"Lockr (Namespace Import)","correct":"import * as Lockr from 'lockr'"}],"quickstart":{"code":"import Lockr from 'lockr';\n\n// Set a prefix for all keys (optional, but good practice)\nLockr.prefix = 'my_app_data_';\n\n// Store various data types. Lockr automatically serializes objects and arrays.\nLockr.set('username', 'Alice Smith');\nLockr.set('userId', 42);\nLockr.set('settings', { theme: 'dark', notifications: true });\nLockr.set('favoriteFruits', ['apple', 'banana', 'cherry']);\n\n// Retrieve values. Lockr automatically deserializes them.\nconsole.log('Username:', Lockr.get('username'));\n// Expected: Username: Alice Smith\n\nconsole.log('Settings:', Lockr.get('settings'));\n// Expected: Settings: { theme: 'dark', notifications: true }\n\n// Use Redis-like set operations (sadd, smembers)\nLockr.sadd('uniqueTags', 'javascript');\nLockr.sadd('uniqueTags', 'typescript');\nLockr.sadd('uniqueTags', 'javascript'); // Adding again has no effect\n\nconsole.log('Unique Tags:', Lockr.smembers('uniqueTags'));\n// Expected: Unique Tags: [ 'javascript', 'typescript' ]\n\n// Remove a key\nLockr.rm('username');\nconsole.log('Username after removal:', Lockr.get('username', 'Guest'));\n// Expected: Username after removal: Guest (demonstrating default value)\n\n// Get all values (only prefixed ones if prefix is set)\nconsole.log('All stored values:', Lockr.getAll());","lang":"typescript","description":"Demonstrates setting a key prefix, storing various data types (strings, numbers, objects, arrays), retrieving them, performing set-like operations, and removing keys."},"warnings":[{"fix":"Monitor the project's GitHub repository for updates and release notes. Consider pinning to a specific beta version and conducting comprehensive regression testing if used in production.","message":"The package is currently in a beta release (0.9.0-beta.2). While functional, it may contain bugs or introduce breaking changes before a stable 1.0.0 release. It is generally not recommended for critical production systems without thorough testing.","severity":"gotcha","affected_versions":">=0.9.0-beta.2"},{"fix":"Ensure consistent use of `Lockr.prefix` across your application. If you need to manage all `localStorage` keys, including non-prefixed ones, you might need to interact directly with the native `localStorage` API for those keys.","message":"When `Lockr.prefix` is set, methods like `Lockr.flush()` and `Lockr.getAll()` will *only* operate on keys that match the configured prefix. Keys stored without the prefix (e.g., via direct `localStorage.setItem` or before the prefix was set) will be ignored by these operations.","severity":"gotcha","affected_versions":"*"},{"fix":"Implement checks for `typeof localStorage !== 'undefined'` before using Lockr in environments where `localStorage` might be absent. Consider using a polyfill or providing a fallback storage mechanism for broader compatibility.","message":"Lockr relies on the browser's native `localStorage` API. If `localStorage` is unavailable (e.g., in private browsing mode, some older browsers, or when running in a Node.js environment without a `localStorage` polyfill), Lockr operations will fail or throw errors without graceful degradation.","severity":"gotcha","affected_versions":"*"},{"fix":"For larger datasets, asynchronous operations, or more complex storage needs, consider alternative storage solutions like IndexedDB or Web SQL. Be mindful of the performance implications when storing or retrieving large objects synchronously.","message":"Lockr (and native `localStorage`) operates synchronously, which can block the main thread for large data operations. It also has limited storage capacity (typically 5-10MB per origin) and stores data as strings, requiring serialization/deserialization.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your code only runs Lockr in a browser context. For SSR, conditionally import/execute Lockr or use a `localStorage` polyfill for Node.js if necessary for testing purposes.","cause":"Attempting to use Lockr in a non-browser environment (e.g., Node.js, server-side rendering) where the global `localStorage` object is not available.","error":"ReferenceError: localStorage is not defined"},{"fix":"Review the data being stored and reduce its size. Consider compressing data before storing, or use alternative storage solutions like IndexedDB for larger datasets.","cause":"The application has attempted to store more data than the browser's `localStorage` quota allows (typically 5-10MB per origin).","error":"DOMException: QuotaExceededError"},{"fix":"Adjust your code to check for `undefined` instead of `null` when retrieving potentially non-existent keys with `Lockr.get`. Alternatively, use the second argument of `Lockr.get(key, defaultValue)` to provide a fallback.","cause":"Developers accustomed to native `localStorage.getItem('key')` which returns `null` for non-existent keys might expect the same from Lockr. `Lockr.get` returns `undefined`.","error":"Lockr.get('key') returns undefined instead of null for non-existent keys."},{"fix":"Always retrieve data using `Lockr.get(key)` to ensure proper deserialization and key prefix handling. Avoid directly accessing `localStorage.getItem()` for data managed by Lockr unless you understand its internal storage format.","cause":"Lockr serializes objects and arrays to JSON strings and often stores them with internal metadata (e.g., `{\"data\": \"value\"}`). If `Lockr.prefix` is set, the key stored in `localStorage` will also be different.","error":"Data saved with Lockr.set is not accessible via localStorage.getItem() directly."}],"ecosystem":"npm","meta_description":null}