@fluid-app/储存管理器

一个用于Fluid Commerce应用程序的公用软件包,为浏览器存储(localStorage)和cookie的工作提供一致的接口. 这个软件包处理浏览器环境中的存储,包括服务器侧渲染.

安装

npm install @fluid-app/storage-manager
# or
yarn add @fluid-app/storage-manager
# or
pnpm add @fluid-app/storage-manager

基本用途

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);

与饼干合作

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);

与流体生态系统的融合

存储管理器被其他 Fluid 包用于存储 :

1. 绘图数据 (@fluid-app/fluid) (中文(简体) )
2. 会话符号 (@fluid-app/fairshare) (法语)
3. 指纹数据 (@fluid-app/fairshare) (法语)
4. 事件队列 (@fluid-app/fairshare) (法语)

与 Fluid SDK 合并的例子 :

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);

存储密钥参考

软件包包括用于一致性的预定义存储密钥 :

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 密钥参考

软件包包括预定义的 cookie 密钥 :

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

API 参考

存储管理类

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<T>(key: string, value: T): void;

  // Retrieve complex data (automatically parsed from JSON)
  getObject<T>(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;
}

工具函数

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

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

服务器- Side 渲染兼容性

此软件包安全地处理浏览器和服务器环境,使其与Next.js等框架相兼容:

// 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 <div>Cart Items: {itemCount}</div>;
}

许可证

麻省理工学院