Enhancing ESHOPMAN Storefront Resilience: Robust Browser Storage Handling in the JavaScript SDK

As an e-commerce platform built on Node.js/TypeScript, ESHOPMAN empowers merchants with flexible headless commerce solutions, often deploying dynamic storefronts via HubSpot CMS. The ESHOPMAN JavaScript SDK is a critical component for these storefronts, managing essential client-side operations, including secure token storage for authenticated user sessions and API interactions.

Recently, our community identified a crucial area for improvement in how the ESHOPMAN JavaScript SDK handles browser storage access. This insight highlights a specific scenario where storefronts, particularly those operating within restricted browser environments, could encounter unexpected failures during initialization.

The Challenge: Incomplete Browser Storage Detection

The ESHOPMAN JavaScript SDK, like many modern web applications, relies on browser storage mechanisms such as localStorage and sessionStorage for various client-side data persistence tasks. The initial implementation for checking storage availability was designed to verify if these properties exist on the window object:

const hasStorage = (storage: "localStorage" | "sessionStorage") => {
  if (typeof window !== "undefined") {
    return storage in window
  }

  return false
}

While this check confirms the presence of the localStorage or sessionStorage property, it does not guarantee access. In specific browser contexts, such as an ESHOPMAN storefront embedded within a sandboxed iframe with an opaque origin (e.g., ), the property might exist, but any attempt to read from or write to it will throw a SecurityError.

Impact on ESHOPMAN Storefronts

When the ESHOPMAN SDK client initializes, it first calls hasStorage. If this returns true (because the property exists), the SDK proceeds to access window.localStorage.getItem(...). In restricted environments, this subsequent access triggers a SecurityError, causing the SDK initialization to fail completely. Instead of gracefully falling back to an in-memory storage solution or a "no storage" mode, the entire storefront application can break, leading to a poor user experience for customers browsing your ESHOPMAN-powered site on HubSpot CMS.

The ESHOPMAN Community Solution: Robust Storage Validation

To address this, the ESHOPMAN community has adopted a more robust approach to validate browser storage access. The recommended fix involves wrapping the storage access in a try/catch block, ensuring that the SDK can gracefully handle scenarios where storage is present but inaccessible:

const hasStorage = (storage: "localStorage" | "sessionStorage") => {
  if (typeof window === "undefined") {
    return false
  }

  try {
    const value = window[storage]

    return Boolean(
      value &&
        typeof value.getItem === "function" &&
        typeof value.setItem === "function"
    )
  } catch {
    return false
  }
}

This revised hasStorage function first checks for the window object's existence. Then, it attempts to access the storage object within a try block. If a SecurityError or any other error occurs during this access, the catch block will execute, correctly returning false. Furthermore, it verifies that the retrieved storage object actually has the expected getItem and setItem methods, confirming its full functionality.

Best Practice for ESHOPMAN Developers

For ESHOPMAN developers building custom storefronts or integrating the ESHOPMAN SDK into complex web applications, this refined storage detection mechanism is a crucial best practice. It ensures that your ESHOPMAN storefronts deployed on HubSpot CMS remain resilient and functional across a wider range of browser environments and security configurations. By preventing SDK initialization failures, you guarantee a more stable and reliable experience for your customers, regardless of how or where your headless commerce application is accessed.