ESHOPMAN Dashboard Development: Troubleshooting Blank Pages and 'ReferenceError' in Your Dev Environment

For ESHOPMAN developers, a smooth local development environment is crucial for building and managing headless commerce storefronts within HubSpot. Recently, some members of our community have encountered a specific challenge when trying to run the ESHOPMAN dashboard's development server: a blank page accompanied by a critical error in the browser console.

Troubleshooting Your ESHOPMAN Dashboard Dev Server: The '__AUTH_TYPE__ is not defined' Error

When setting up or working on the ESHOPMAN dashboard locally, developers might run the development server (often via a command like yarn dev). Instead of seeing the expected login page or dashboard interface, the browser displays a blank page, and the console reports an Uncaught ReferenceError: __AUTH_TYPE__ is not defined. This error prevents the dashboard from loading entirely, halting development efforts.

Uncaught ReferenceError: __AUTH_TYPE__ is not defined
    at src/lib/client/client.ts

Understanding the Root Cause

This issue stems from how the ESHOPMAN dashboard's development server is configured compared to its production build process. The ESHOPMAN dashboard relies on several build-time constants for various functionalities, including authentication type, JWT token storage, and maximum file upload size. Specifically, three constants were identified as missing from the development server's configuration:

• __AUTH_TYPE__
• __JWT_TOKEN_STORAGE_KEY__
• __MAX_UPLOAD_FILE_SIZE__

These constants are correctly defined in the production bundler configuration. However, the standalone development server configuration (found in packages/admin/dashboard/vite.config.mts) only defines a subset of these, such as __BASE__, __BACKEND_URL__, and __STOREFRONT_URL__.

The core of the problem lies in how development tools like Vite handle these "define" constants. Vite performs a direct text substitution for these values during the build process. If a constant like __AUTH_TYPE__ is referenced in the source code but not explicitly defined in the Vite configuration, the JavaScript engine encounters an undeclared identifier. This immediately throws a ReferenceError, even before any nullish coalescing operators (like ?? "session") can provide a fallback value. Consequently, the application crashes before it even starts, leading to the blank page.

Steps to Reproduce (and Confirm)

If you suspect you're facing this issue, you can typically reproduce it with these steps in your ESHOPMAN development environment:

1. Ensure your ESHOPMAN project dependencies are installed and the dashboard's dependencies are built.
2. Navigate to the dashboard directory (e.g., cd packages/admin/dashboard).
3. Start the development server: yarn dev.
4. Open your browser to the local development URL (e.g., http://localhost:5173/).

If you see a blank page and the ReferenceError in your browser's developer console, you've confirmed the issue.

The Community-Identified Solution

The resolution involves updating the ESHOPMAN dashboard's development server configuration to include the missing build-time constants with their default values. By adding these definitions to the define block within packages/admin/dashboard/vite.config.mts, the Vite build process can correctly substitute the values, preventing the ReferenceError.

The required constants and their typical default values are:

• __AUTH_TYPE__: Defaults to "session" for session-based authentication.
• __JWT_TOKEN_STORAGE_KEY__: Typically undefined if not using JWT.
• __MAX_UPLOAD_FILE_SIZE__: Defaults to 1048576 (which is 1 MB) for file upload limits.

Implementing this fix ensures that the ESHOPMAN dashboard's development server loads correctly, allowing developers to access the login page and subsequently work on storefront management, HubSpot CMS deployments, and custom integrations using the Admin API and Store API. This is vital for maintaining productivity and leveraging ESHOPMAN's headless commerce capabilities effectively.

While an automated fix for this specific issue was explored, the complexity meant it was escalated to the ESHOPMAN core team for a robust solution. In the meantime, understanding this mechanism empowers developers to troubleshoot and apply manual adjustments to their local environments, keeping their ESHOPMAN projects moving forward.