@react-solutions/vault

A powerful, lightweight React & Next.js library providing secure, encrypted storage utilities for localStorage, sessionStorage, Cache API, and Cookies. It features AES-GCM encryption, automatic serialization, and full TypeScript support.

📦 Installation

npm install @react-solutions/vault

🚀 Features

• 🔒 Multi-Layer Encryption - AES-GCM encryption for all storage types.
• 🍪 Cookie Support - Comprehensive cookie management with security options.
• 📂 Cache API Integration - Store large datasets securely using the browser's Cache API.
• 🔄 Atomic Updates - Support for functional updates and partial merges.
• 🌍 SSR Compatible - Works seamlessly with Next.js (graceful fallbacks for server-side).
• 🗝️ Custom Keys - Configure passphrase, salt, and namespace per call.
• ⚡ Ultra Lightweight - No dependencies and tree-shakable.

📚 API Reference

1. Local Storage API

Persistent storage that stays even after the browser is closed.

| Method | Description | | :-------------------------------------- | :------------------------------------------------------------------ | | setItem(key, value, options?) | Encrypts and saves data to localStorage. | | getItem<T>(key, options?) | Retrieves and decrypts data from localStorage. | | updateItem<T>(key, updater, options?) | Updates existing data (merges objects or uses an updater function). | | removeItem(key) | Deletes a specific item from localStorage. | | hasItem(key) | Checks if a key exists in localStorage. | | clear() | Clears all localStorage data. |

Usage:

import { setItem, getItem, updateItem } from "@react-solutions/vault";

setItem("user", { name: "Alice" });
const user = getItem<{ name: string }>("user");
updateItem("user", { age: 25 }); // Merges with existing data

2. Session Storage API

Storage that persists only for the duration of the page session (tab).

| Method | Description | | :----------------------------------------- | :----------------------------------------------- | | setSession(key, value, options?) | Encrypts and saves data to sessionStorage. | | getSession<T>(key, options?) | Retrieves and decrypts data from sessionStorage. | | updateSession<T>(key, updater, options?) | Updates existing session data. | | removeSession(key) | Deletes a specific item from sessionStorage. | | hasSession(key) | Checks if a key exists in sessionStorage. | | clearSession() | Clears all sessionStorage data. |

Usage:

import { setSession, getSession } from "@react-solutions/vault";

setSession("temp_data", { id: 123 });

3. Cache API

Ideal for larger datasets or offline storage.

| Method | Description | | :--------------------------------------- | :------------------------------------------------ | | setCache(key, value, options?) | Stores encrypted data in the browser's Cache API. | | getCache<T>(key, options?) | Retrieves and decrypts data from the Cache API. | | updateCache<T>(key, updater, options?) | Updates existing cached data. | | removeCache(key, options?) | Removes a specific resource from the cache. | | hasCache(key, options?) | Checks if a resource exists in the cache. | | clearCache(options?) | Deletes an entire cache bucket. |

Usage:

import { setCache, getCache } from "@react-solutions/vault";

await setCache("api_response", { data: [...] });
const response = await getCache("api_response");

4. Cookie API

Manage cookies with encryption and security attributes.

| Method | Description | | :---------------------------------------- | :-------------------------------------------------------------- | | setCookie(key, value, options?) | Sets an encrypted cookie with expires, path, secure, etc. | | getCookie<T>(key, options?) | Retrieves and decrypts a cookie value. | | updateCookie<T>(key, updater, options?) | Updates a cookie via merge or updater function. | | removeCookie(key, options?) | Deletes a cookie. | | hasCookie(key) | Checks if a cookie exists. | | clearCookies() | Clears all accessible cookies. |

Usage:

import { setCookie, getCookie } from "@react-solutions/vault";

setCookie("theme", "dark", { expires: 30, secure: true });
const theme = getCookie("theme");

5. Crypto Utilities

Low-level encryption and key generation tools.

| Method | Description | | :--------------------------------- | :----------------------------------------------------------- | | encrypt(data, options?) | Encrypts any JSON-serializable data into a secure string. | | decrypt<T>(ciphertext, options?) | Decrypts a vault-encrypted string back to its original type. | | getCryptoKey(length?) | Generates a cryptographically secure SHA-256 hex string. |

Usage:

import { encrypt, decrypt, getCryptoKey } from "@react-solutions/vault";

// Generate a 32-character secure key
const key = getCryptoKey(32);

// Encrypt data manually
const secretData = encrypt({ pin: 1234 }, { secretKey: key });

// Decrypt data manually
const original = decrypt<{ pin: number }>(secretData, { secretKey: key });

🔑 Custom Encryption Settings

You can provide custom encryption settings (passphrase, salt, namespace) in the options object for any of the methods.

setItem("sensitive", { token: "123" }, { passphrase: "my-secret-key", salt: "custom-salt" });

📝 Next.js (SSR) Usage

This package is safe to use in Next.js. Methods called on the server will return null or false without throwing errors, ensuring your build and server-side rendering remain stable.

// This is safe even in a Server Component or during SSR
const data = getItem("data");

⚡ Example: Using Types

type User = { id: string; name: string };
const user = await getItem<User>("user");

📝 TypeScript Support

This package is written in TypeScript and includes full type definitions. All exported functions and hooks are fully typed.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

Made with ❤️ for React & Next.js developers