@react-solutions/storage

📦 Installation

npm install @react-solutions/storage

🚀 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
• 🧩 React Hook API - useSecureStorage() for seamless React integration
• 💾 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 hooks and utilities you need:

import {
    setItem,
    getItem,
    setSession,
    getSession,
    updateItem,
    updateSession,
    removeItem,
    removeSession,
    clearAll,
    clearSession,
    hasItem,
    hasSession,
} from "@react-solutions/storage";
// Or use the hook for React integration:
import { useSecureStorage } from "@react-solutions/storage";

Using the React Hook

import { useSecureStorage } from "@react-solutions/storage";

function MyComponent() {
    const storage = useSecureStorage({
        passphrase: "my-secret-phrase", // optional, for encryption
        salt: "custom-salt", // optional, for encryption
        namespace: "my-app", // optional, for isolation
    });

    // Set an item with optional expiry (in seconds)
    const save = () => {
        storage.setItem("user", { name: "Alice" }, { ttl: 3600 });
    };

    // Get an item
    const load = () => {
        const value = storage.getItem("user");
        console.log(value);
    };

    // Remove an item
    const forget = () => {
        storage.removeItem("user");
    };

    // Clear all persistent storage
    const clear = () => {
        storage.clearAll();
    };

    return (
        <div>
            <button onClick={save}>Save</button>
            <button onClick={load}>Load</button>
            <button onClick={forget}>Remove</button>
            <button onClick={clear}>Clear All</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.

const user = 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

clearAll(options?)

Clear all encrypted localStorage in the current namespace.

clearAll();

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.

const session = 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();

🔑 Example: Custom Encryption Settings

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

⚡ Example: Using Types

type User = { id: string; name: string };
const user = 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

🔗 Related

• Axios Documentation
• React Hooks Documentation

💡 Tips

1. Always configure baseURL: Use updateConfig or createConfig to set your base URL
2. Use interceptors for global logic: Add authentication tokens, logging, or error handling
3. Leverage state objects: Use isLoading, isSuccess, isError for UI state management
4. Handle errors properly: Use both onError callbacks and .catch() for comprehensive error handling
5. GraphQL errors: GraphQL errors are automatically converted to HTTP-like error objects for consistent handling

Made with ❤️ for React developers