Package Exports

@react-solutions/vault

Readme

@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");

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