unify-storage 🚀

A unified storage layer for Next.js that works on both server and client without crashes.

Features ✨

• 🔄 Dual Storage: Automatically stores data in both localStorage and cookies
• 🛡️ Safe Fallbacks: Gracefully handles server-side rendering (returns null on server)
• 📦 Lightweight: No dependencies, minimal footprint
• 🔒 Type-Safe: Full TypeScript support
• ⚡ Server Safe: Can be imported in Server Components without crashing

Installation

npm install unify-storage

Usage

⚠️ Important: Server vs Client Components

This package is safe to import in Server Components, but storage operations only work in the browser.

| Environment | get() | set() / remove() | |-------------|---------|----------------------| | Client (Browser) | Returns value | Works as expected | | Server (Node.js) | Returns null | Operation skipped (no-op) |

Correct Usage in Next.js

To actually store or retrieve data, you must use this in a Client Component (using "use client") or inside a useEffect.

Option 1: Client Component (Recommended)

"use client"; // <--- Required for interactivity

import { smartStorage } from "unify-storage";

const MyComponent = () => {
    const saveToken = () => {
        smartStorage.set("token", "12345");
        console.log("Saved!");
    };

    return <button onClick={saveToken}>Save Token</button>;
}

export default MyComponent;

Option 2: Using useEffect

"use client";

import { useEffect, useState } from "react";
import { smartStorage } from "unify-storage";

const Profile = () => {
    const [token, setToken] = useState<string | null>(null);

    useEffect(() => {
        // Only runs in the browser
        const stored = smartStorage.get("token");
        setToken(stored);
    }, []);

    return <div>Token: {token}</div>;
}

What happens in a Server Component?

If you use it in a Server Component without "use client", it will not crash, but it will not save anything.

// ❌ This is a Server Component
import { smartStorage } from "unify-storage";

const ServerComponent = () => {
    // ⚠️ This runs on the server!
    // Result: Operation skipped, nothing is saved.
    smartStorage.set("token", "12345"); 

    return <div>Check console logs</div>;
}

API Reference

smartStorage.get(key: string): string | null

Retrieves a value from storage. Checks localStorage first, then falls back to cookies. Returns null if called on the server.

const token = smartStorage.get("token");

smartStorage.set(key: string, value: string): void

Stores a value in both localStorage and cookies (30 days expiry by default). Skips operation if called on the server.

smartStorage.set("user", "john_doe");

smartStorage.remove(key: string): void

Removes a value from both localStorage and cookies. Skips operation if called on the server.

smartStorage.remove("token");

smartStorage.has(key: string): boolean

Checks if a key exists in storage.

if (smartStorage.has("token")) {
    // Token exists
}

smartStorage.clear(): void

Clears all items from localStorage (cookies are not affected).

smartStorage.clear();

How It Works

1. Environment Detection: The package checks typeof window !== "undefined" to determine if it's running in the browser.
2. Client-Side: Uses localStorage as primary storage with cookies as backup.
3. Server-Side: Safely returns null or skips operations to prevent hydration mismatches or crashes.
4. Cookies: Automatically set with SameSite=Lax and 30-day expiry.