Storage Manager for Browser-Based JavaScript Frameworks

A universal browser and server storage manager for Next.js projects with support for localStorage, sessionStorage, and cookies, with optional AES encryption.

📦 Installation

npm install @lonewolfspace/storage-manager-ts
# or
yarn add @lonewolfspace/storage-manager-ts

✨ Features

• 🔐 Optional AES encryption support
• 🧱 Unified API for localStorage, sessionStorage, and cookies
• ✅ TypeScript support (Syntactic Sugar)
• ✅ Safe for use in client components
• 📦 Cookie operations based on js-cookie
• 📄 Modular import and usage flexibility
• 🌐 Support for server-side cookie storage in Next.js API routes and Server Actions

🔧 Configuration

Client-side Configuration

import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";

StorageManagerConfig.configureClient({
  encryption: true,
  keyPrefix: "secure_", // This option is under development 🚧
  secretKey: "your-128bit-secret-key", // Load from .env 🔐 (for Nextjs make sure to use "NEXT_PUBLIC_" prefix)
});

Server-side Configuration

import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";

StorageManagerConfig.configureServer({
  encryption: true,
  keyPrefix: "secure_", // This option is under development 🚧
  secretKey: "your-128bit-secret-key", // Load from .env 🔐 
});

🔐 Set Secret Key for Encryption (Optional)

StorageManager.local.setSecretKey("your-secret-key");
StorageManager.session.setSecretKey("your-secret-key");
StorageManager.cookie.setSecretKey("your-secret-key");

⚠️ If you skip setting a secret key, values will be stored in plain text.

💾 Usage Examples

📦 LocalStorage Example

StorageManager.local.setItem("key", "value");
const value = StorageManager.local.getItem("key");
StorageManager.local.removeItem("key");

🗂 SessionStorage Example

StorageManager.session.setItem("sessionKey", "sessionValue");
const value = StorageManager.session.getItem("sessionKey");
StorageManager.session.removeItem("sessionKey");

🍪 Cookie Example (Client-side Only)

StorageManager.cookie.setCookie("cookieKey", "cookieValue", {
  path: "/",
  maxAge: 60 * 60 * 24, // 1 day
});

const cookie = StorageManager.cookie.getCookie("cookieKey");
StorageManager.cookie.deleteCookie("cookieKey");

⚙️ Use in Next.js Client Components

"use client";

import { StorageManager } from "@lonewolfspace/storage-manager-ts";

StorageManager.local.setItem("theme", "dark");
const theme = StorageManager.local.getItem("theme");

🧩 Modular Import

import {
  StorageManagerConfig,
  ClientLocalStorageManager,
  ClientSessionStorageManager,
  ClientCookieManager,
} from "@lonewolfspace/storage-manager-ts";

ClientLocalStorageManager.setItem("foo", "bar");
ClientSessionStorageManager.setItem("foo", "bar");
ClientCookieManager.setCookie("foo", "bar");

🌐 Server-side Cookie Storage

✅ API Route Example

// app/api/cookie/route.ts

import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";
import { ServerCookieManager } from "@lonewolfspace/storage-manager-ts/server";
import { redirect } from "next/navigation";

StorageManagerConfig.configureServer({
  encryption: true,
  keyPrefix: "secret_",
  secretKey: "0000000000000000",
});

export async function GET() {
  await ServerCookieManager.setCookie("server_cookie", "Hello World");
  redirect("/");
}

✅ Server Action Example

"use server";

import { ServerCookieManager } from "@lonewolfspace/storage-manager-ts/server";

export const store_cookie = async () => {
  await ServerCookieManager.setCookie("server_cookie", "Hello World", {
    maxAge: 10,
  });
};

Then use this with form actions

✅ Usage in layout.tsx

import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";
import { ServerCookieManager } from "@lonewolfspace/storage-manager-ts/server";

export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  StorageManagerConfig.configureServer({
    encryption: true,
    keyPrefix: "secret_",
    secretKey: "0000000000000000", 
  });

  return <>...</>;
}

🧪 Client Demo Page Example

"use client";
import React, { useEffect, useState } from "react";
import {
  StorageManagerConfig,
  ClientLocalStorageManager,
  ClientSessionStorageManager,
  ClientCookieManager,
} from "@lonewolfspace/storage-manager-ts";

const StoragePage = () => {
  StorageManagerConfig.configureClient({
    encryption: false,
    keyPrefix: "secret_",
    secretKey: "0000000000000000",
  });

  const [message, setMessage] = useState("");

  useEffect(() => {
    const local = ClientLocalStorageManager.getItem("greeting");
    const session = ClientSessionStorageManager.getItem("session");
    const cookie = ClientCookieManager.getCookie("client_cookie");

    console.log("LocalStorage:", local);
    console.log("SessionStorage:", session);
    console.log("Client Cookie:", cookie);
  }, []);

  return (
    <div className="p-4 space-y-4">
      <h1 className="text-xl font-bold">Storage Test (Client)</h1>

      <button
        onClick={() => {
          ClientLocalStorageManager.setItem("greeting", "Hello Local!");
          setMessage("Stored in localStorage");
        }}
        className="px-4 py-2 bg-blue-500 text-white rounded"
      >
        Set LocalStorage
      </button>

      <button
        onClick={() => {
          ClientSessionStorageManager.setItem("session", "Hello Session!");
          setMessage("Stored in sessionStorage");
        }}
        className="px-4 py-2 bg-green-500 text-white rounded"
      >
        Set SessionStorage
      </button>

      <button
        onClick={() => {
          ClientCookieManager.setCookie("client_cookie", "Hello Cookie!", {
            expires: 1,
          });
          setMessage("Stored in client cookies");
        }}
        className="px-4 py-2 bg-purple-500 text-white rounded"
      >
        Set Client Cookie
      </button>

      <div className="text-gray-700">{message}</div>
    </div>
  );
};

export default StoragePage;

🧾 API Reference

StorageManager.local / StorageManager.session

| Method | Description | | --------------------- | --------------------------- | | setSecretKey(key) | Sets the AES encryption key | | setItem(key, value) | Stores the value | | getItem(key) | Retrieves the value | | removeItem(key) | Deletes the key |

StorageManager.cookie

| Method | Description | | --------------------------------- | --------------------------- | | setSecretKey(key) | Sets the AES encryption key | | setCookie(key, value, options?) | Sets a cookie | | getCookie(key) | Gets a cookie value | | deleteCookie(key, options?) | Deletes the cookie |

ServerCookieManager

| Method | Description | | --------------------------------- | ----------------------------- | | setCookie(key, value, options?) | Sets a cookie on the server | | getCookie(key) | Gets a cookie from the server | | deleteCookie(key, options?) | Deletes a server cookie |

📄 License

MIT © Manas Saha Roy