@fluid-app/storage-manager

A utility package for Fluid Commerce applications that provides a consistent interface for working with browser storage (localStorage) and cookies. This package handles storage across browser environments including server-side rendering.

Installation

``bash
npm install @fluid-app/storage-manager


or

yarn add @fluid-app/storage-manager

or

pnpm add @fluid-app/storage-manager
`

Basic Usage

`typescript
import { STORAGE_KEYS, StorageManager } from "@fluid-app/storage-manager";

// Create a storage manager instance
const storageManager = new StorageManager();

// Store string data
storageManager.setItem(STORAGE_KEYS.CART, "cart_abc123");

// Retrieve string data
const cartToken = storageManager.getItem(STORAGE_KEYS.CART); // "cart_abc123"

// Store complex data (automatically serialized to JSON)
storageManager.setObject(STORAGE_KEYS.CART, {
cart_token: "cart_abc123",
items: [
{ id: 1, variant_id: 11601, quantity: 2 },
{ id: 2, variant_id: 11602, quantity: 1 },
],
subtotal: "29.99",
});

// Retrieve complex data (automatically parsed from JSON)
const cart = storageManager.getObject(STORAGE_KEYS.CART);
console.log(cart.items.length); // 2

// Remove data
storageManager.removeItem(STORAGE_KEYS.CART);
`

Working with Cookies

`typescript
import { COOKIE_KEYS, getCookie } from "@fluid-app/storage-manager";
import { getCountryFromLocale } from "path/to/localeUtils";

// Read a cookie value
const countryCookie = getCookie(COOKIE_KEYS.COUNTRY); // "US"

// The storage manager can also retrieve values from cookies as fallback
const storageManager = new StorageManager();

// Get country code with fallback to cookies
const locale = storageManager.getItem(STORAGE_KEYS.LOCALE);
const countryCode = getCountryFromLocale(locale);

// Get locale with fallback to cookies
const locale = storageManager.getItem(STORAGE_KEYS.LOCALE);
`

Integration with Fluid Ecosystem

The Storage Manager is used by other Fluid packages to store:

1. Cart data (@fluid-app/fluid)
2. Session tokens (@fluid-app/fairshare)
3. Fingerprint data (@fluid-app/fairshare)
4. Event queues (@fluid-app/fairshare)

Example integration with Fluid SDK:

`typescript
import { initializeFluid } from "@fluid-app/fluid";

// Initialize Fluid SDK
initializeFluid({
fluidShop: "your-shop-id",
// Attribution is now handled server-side via the settings API
});

// You can still access other stored data if needed
const storageManager = new StorageManager();
const cartData = storageManager.getObject(STORAGE_KEYS.CART);
console.log("Current cart:", cartData);
`

Storage Keys Reference

The package includes predefined storage keys for consistency:

`typescript
const STORAGE_KEYS = {
ATTRIBUTION: "fs_attribution", // Attribution data
ATTRIBUTION_CACHE: "fs_attribution_cache", // Cached attribution data
CART: "fs_cart", // Cart data
CLIENT_SETTINGS: "fs_client_settings",
CONFIG: "fs_config", // SDK configuration
COUNTRY: "fs_country", // Country code
EVENT_QUEUE: "fs_event_queue", // Queued analytics events
FINGERPRINT: "fs_fingerprint", // Browser fingerprint
LOCALE: "fs_locale", // Locale
SERVER_SETTINGS: "fs_server_settings", // Server settings
SESSION: "fs_session", // Session token
USER_ID: "fs_user_id", // User ID for identified users
};
`

Cookie Keys Reference

The package includes predefined cookie keys:

`typescript
const COOKIE_KEYS = {
COUNTRY: "country", // Country code cookie (often set by Cloudflare)
LOCALE: "locale", // Locale cookie
};
`

API Reference

$3

`typescript
class StorageManager {
// Store string data
setItem(key: string, value: string): void;

// Retrieve string data
getItem(key: string): string | null;

// Remove data
removeItem(key: string): void;

// Store complex data (automatically serialized to JSON)
setObject(key: string, value: T): void;

// Retrieve complex data (automatically parsed from JSON)
getObject(key: string): T | null;

// Get country code from storage or cookies
getCountryCode(): string;

// Set country code
setCountryCode(countryCode: string): void;

// Get locale from storage or cookies
getLocale(): string | null;

// Set locale
setLocale(locale: string): void;
}
`

$3

`typescript
// Check if code is running in a browser environment
function isBrowser(): boolean;

// Get a cookie value by name
function getCookie(name: string): string | null;
`

Server-Side Rendering Compatibility

This package safely handles both browser and server environments, making it compatible with frameworks like Next.js:

`typescript
// In a Next.js component (works in both client and server components)
import { StorageManager } from "@fluid-app/storage-manager";

export default function CartIndicator() {
// Create a client component that uses localStorage safely
"use client";

const [itemCount, setItemCount] = useState(0);

useEffect(() => {
const storageManager = new StorageManager();
const cart = storageManager.getObject("fs_cart");
setItemCount(cart?.items?.length || 0);
}, []);

return

;
}
``

License

MIT