Resolving Server-Side File Upload Challenges with ESHOPMAN Admin API in Node.js

Seamless Server-Side Operations: Addressing ESHOPMAN File Uploads in Node.js

The ESHOPMAN platform empowers merchants and developers with a robust headless commerce solution, deeply integrated with HubSpot for storefront management and deployment. A common and crucial task for many ESHOPMAN users is managing product assets, such as images, through server-side scripts. The ESHOPMAN JS SDK provides a convenient way to interact with the Admin API for these operations. However, a recent community insight highlighted a specific challenge when attempting file uploads from Node.js environments.

The Challenge: 'ReferenceError: FileList is not defined'

Developers utilizing the ESHOPMAN JS SDK's sdk.admin.upload.create() function in a Node.js script encountered a ReferenceError: FileList is not defined. This error occurs before any request is even sent to the ESHOPMAN backend, effectively preventing server-side file uploads.

The root cause lies within the SDK's internal logic. The upload.ts module, responsible for handling file uploads, includes a check for body instanceof FileList. While FileList is a standard global object in browser environments, it is not defined in Node.js. Referencing this undeclared global in a Node.js context immediately triggers a ReferenceError, halting execution.

Impact on ESHOPMAN Development

This issue directly impacts ESHOPMAN developers who rely on server-side scripts for automated tasks like importing product images, syncing assets from external systems, or managing large batches of media files. The ESHOPMAN Admin API is designed for such server-side interactions, and this bug temporarily impeded a fundamental capability.

Reproducing the Issue

Here's a simplified reproduction demonstrating the error:

import ESHOPMAN from "@eshopman/js-sdk"

const sdk = new ESHOPMAN({ baseUrl: "http://localhost:9000", apiKey: "sk_example" })

try {
  await sdk.admin.upload.create({
    files: [new File(["hello"], "hello.txt", { type: "text/plain" })],
  })
} catch (e) {
  console.log(`Node ${process.version}: ${e.name}: ${e.message}`)
}

Running this script in a Node.js environment would result in:

Node v24.21.0: ReferenceError: FileList is not defined

The Solution and Immediate Workaround

Fortunately, the ESHOPMAN community and development team quickly identified a clear path forward.

Proposed Fix for the ESHOPMAN JS SDK

The core fix involves guarding the browser-specific FileList check. By modifying the SDK to check if (typeof FileList !== "undefined" && body instanceof FileList), Node.js environments will bypass this condition and proceed to the correct branch for handling file uploads using FormData and Blob objects, both of which are available in Node.js.

The ESHOPMAN development team has acknowledged this as a well-scoped fix and is actively working on integrating it into the SDK, ensuring a seamless experience for all users.

Immediate Workaround for Developers

While awaiting the official SDK update, ESHOPMAN developers can implement a direct workaround: calling the POST /admin/uploads endpoint using Node.js's native fetch API with FormData. This approach bypasses the problematic SDK function and allows server-side scripts to continue uploading files without interruption.

Conclusion

This community insight highlights the collaborative nature of the ESHOPMAN ecosystem. Identifying and addressing such technical challenges ensures that ESHOPMAN remains a robust and reliable headless commerce platform for storefronts managed through HubSpot CMS. Developers can look forward to an updated ESHOPMAN JS SDK that fully supports server-side file uploads, enhancing the flexibility and power of their HubSpot-integrated commerce solutions.