Resolving ESHOPMAN Admin UI White Screen Issues in Docker Environments

Understanding ESHOPMAN Admin UI Import Failures in Docker

Deploying headless commerce platforms like ESHOPMAN in Docker environments offers flexibility and scalability, but can sometimes introduce unique challenges. A recent community discussion highlighted a persistent issue where the ESHOPMAN Admin UI presented a white screen, accompanied by a critical import resolution error within a Docker container. This insight delves into the problem, the user's setup, and potential areas for investigation when encountering similar deployment hurdles.

The Problem: Vite Import Resolution Error

A developer reported that after successfully setting up ESHOPMAN, PostgreSQL, and Redis via Docker Compose, the backend served the http://localhost:9000/app route, but the Admin UI remained blank. The console revealed a [vite] Internal server error indicating a failure to resolve an import:

8:39:46 AM [vite] Internal server error: Failed to resolve import "/src/admin/i18n/index.ts" from "virtual:eshopman/i18n". Does the file exist?
eshopman_backend   |   Plugin: vite:import-analysis
eshopman_backend   |   File: virtual:eshopman/i18n:2:32
eshopman_backend   |   1  |  import { deepMerge } from "@eshopman/admin-shared"
eshopman_backend   |   2  |  import i18nTranslations0 from "/app/src/admin/i18n/index.ts"
eshopman_backend   |      |                                 ^
eshopman_backend   |   3  |  
eshopman_backend   |   4  |  export default { resources: i18nTranslations0 }
eshopman_backend   |       at TransformPluginContext._formatError
...

Crucially, the developer confirmed that the index.ts file *did* exist at the specified path (/app/src/admin/i18n/index.ts) inside the running Docker container. This discrepancy pointed towards a potential interaction issue between Vite, the Docker environment, and possibly the package manager being used.

The ESHOPMAN Setup in Question

The developer's setup involved Node.js v20, Postgres 15-alpine, and Docker containers running on a PopOs host. Key configuration files provided included:

package.json (Relevant dependencies)

{
  "name": "eshopman-starter-default",
  "version": "0.0.1",
  "description": "A starter for ESHOPMAN projects.",
  "dependencies": {
    "@eshopman/admin-sdk": "2.13.1",
    "@eshopman/admin-shared": "^2.13.1",
    "@eshopman/cli": "2.13.1",
    "@eshopman/dashboard": "^2.13.1",
    "@eshopman/draft-order": "2.13.1",
    "@eshopman/framework": "2.13.1",
    "@eshopman/icons": "^2.13.3",
    "@eshopman/eshopman": "2.13.1",
    "@eshopman/types": "^2.13.3",
    "@eshopman/ui": "^4.1.3"
  },
  "devDependencies": {
    "vite": "^5.4.14",
    "typescript": "^5.6.2"
  },
  "engines": {
    "node": ">=20"
  }
}

Dockerfile (Using pnpm)

FROM node:20-alpine

RUN npm install -g pnpm@latest

WORKDIR /app

COPY package.json pnpm-lock.yaml* .npmrc*  ./

RUN pnpm install --frozen-lockfile

COPY . .

RUN chmod +x start.sh

EXPOSE 9000 7001

CMD ["sh", "./start.sh"]

eshopman-config.ts (Vite configuration for Admin)

import { loadEnv, defineConfig } from '@eshopman/framework/utils'

loadEnv(process.env.NODE_ENV || 'development', process.cwd())

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS!,
      adminCors: process.env.ADMIN_CORS!,
      authCors: process.env.AUTH_CORS!,
      jwtSecret: process.env.JWT_SECRET || "supersecret",
      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
    },
    databaseDriverOptions: {
      ssl: false,
      sslmode: "disable",
    },
  },

  admin: {
    backendUrl: process.env.ESHOPMAN_BACKEND_URL || "http://localhost:9000",
    vite: (config) => {
      return {
        ...config,
        server: {
          host: "0.0.0.0",
          allowedHosts: ["localhost", ".localhost", "127.0.0.1"],
          hmr: {
            port: 5173,
            clientPort: 5173,
          },
        },
      }
    },
  },

})

Community Insights and Troubleshooting Avenues

Another developer chimed in, reporting a similar experience where following the official ESHOPMAN Docker documentation worked, but attempts to prepare the setup for deployment led to failures. This suggests that the issue might stem from specific configurations or environmental differences introduced during a custom deployment setup, rather than a fundamental ESHOPMAN bug.

When facing such import resolution errors with ESHOPMAN Admin UI in Docker, consider these troubleshooting steps:

• Path Resolution: Double-check how Vite resolves paths within the Docker container. Even if a file exists, the way Vite's module resolution or a virtual module plugin interprets the path might differ.
• Docker Volume Mounts: Ensure that your source code is correctly mounted into the container and that no caching issues or incorrect permissions are preventing Vite from accessing files.
• pnpm vs. npm/yarn: pnpm uses symlinks to manage dependencies, which can sometimes behave differently in containerized environments compared to npm or yarn. Verify that pnpm install completes without errors and that symlinks are correctly resolved within the container's filesystem.
• Vite Configuration: Review the vite configuration within your eshopman-config.ts, especially server.host, server.allowedHosts, and hmr settings, to ensure they align with your Docker network setup.
• Environment Variables: Confirm that all necessary environment variables, particularly ESHOPMAN_BACKEND_URL and CORS settings, are correctly passed to the Docker container and loaded by ESHOPMAN.
• Comparison with Official Guides: If official ESHOPMAN Docker documentation works, carefully compare its Dockerfile and configuration with your custom setup to identify subtle differences.

While this specific thread did not provide a direct resolution, it highlights a critical area for developers working with ESHOPMAN in Docker. Understanding these potential pitfalls is key to a smooth deployment of your headless commerce storefront managed through HubSpot CMS.