@react-solutions/vault

📦 Installation

npm install @react-solutions/vault

🚀 Features

• 🔒 Encrypted Storage - AES-GCM encryption for both localStorage and sessionStorage
• 🗝️ Custom Encryption Keys - Easily configure passphrase, salt, namespace for isolation
• ⏳ TTL (Expiration) - Set expiration and auto-removal for any value
• 🔄 Atomic Updates - Support for functional updates (like React setState)
• 🚀 Full TypeScript Support - Strict types and intellisense everywhere
• 💾 Persistent + Session - Choose persistent (localStorage) or session-based (sessionStorage) storage
• 🧼 Clear & Remove - One-call clear all/individual keys
• 🕵️ Existence Check - Easily check if a key exists
• 🔍 Auto JSON Handling - Transparent serialization and deserialization
• ⚡ Ultra Lightweight - No dependencies, tree-shakable, and small bundle size

📚 Quick Start

🛠 Usage

First, import the utilities you need:

import {
  setItem,
  getItem,
  setSession,
  getSession,
  updateItem,
  updateSession,
  removeItem,
  removeSession,
  clear,
  clearSession,
  hasItem,
  hasSession,
  useGetItem,
  useGetSession
} from "@react-solutions/vault";

Reactive Hooks

Use useGetItem or useGetSession to subscribe to storage changes. The component will re-render whenever the storage key changes.

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

function MyComponent() {
  // Automatically updates when "user" changes in localStorage
  const user = useGetItem("user"); 

  const save = () => {
    setItem("user", { name: "Alice" }, { ttl: 3600 });
  };

  return (
    <div>
      <p>User: {user?.name}</p>
      <button onClick={save}>Save User</button>
    </div>
  );
}

Standalone API Usage

setItem(key, value, options?)

Save a value to encrypted localStorage. Optionally set a TTL (expiration in seconds).

setItem("user", { name: "Alice" }, { ttl: 3600 });
// After 1 hour, the entry will be auto-deleted

getItem<T = any>(key, options?)

Read and decrypt a value from localStorage. Returns a Promise.

const user = await getItem("user"); // { name: "Alice" } | null

updateItem(key, updater, options?)

Update a value atomically (updater can be a function or value).

updateItem("user", (prev) => ({ ...prev, age: 30 }));

removeItem(key, options?)

Remove an item from localStorage.

removeItem("user");

hasItem(key, options?)

Check if a key exists and isn't expired.

const exists = hasItem("user"); // boolean

clear(options?)

Clear all encrypted localStorage in the current namespace.

clear();

setSession(key, value, options?)

Save a value to encrypted sessionStorage.

setSession("sessionData", { temp: true });

getSession<T = any>(key, options?)

Read and decrypt a value from sessionStorage. Returns a Promise.

const session = await getSession("sessionData");

updateSession(key, updater, options?)

Update a session value.

updateSession("sessionData", (prev) => ({ ...prev, lastSeen: Date.now() }));

removeSession(key, options?)

Delete a session value.

removeSession("sessionData");

hasSession(key, options?)

Check if a session key exists and isn't expired.

const active = hasSession("sessionData");

clearSession(options?)

Clear all encrypted sessionStorage in the current namespace.

clearSession();

⚙️ Configuration

You can configure global settings like passphrase, salt, and namespace.

import { configureLocal, configureSession } from "@react-solutions/vault";

configureLocal({
  passphrase: "my-secret-phrase",
  salt: "custom-salt",
  namespace: "my-app"
});

configureSession({
  namespace: "my-app-session"
});

🔑 Example: Custom Encryption Settings per Call

setItem(
  "sensitive",
  { token: "123" },
  { passphrase: "mysecret", salt: "mysalt", namespace: "secure" }
);

⚡ 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 developers