service-finder/docs/frontend_white_screen_analysis_2026-06-07.md

Frontend White Screen Analysis - 2026-06-07

Summary

The app.servicefinder.hu page was loading as a blank/white screen. Root cause: Missing flag-icons npm package inside the frontend container.

---

1. Investigation Steps

1.1 Docker Container Status

• sf_public_frontend: Up (running)
• sf_api: Up (running)
• Backend API reachable: localhost:8000/api/v1/health → responds

1.2 Frontend Container Logs

Primary error (repetitive):

[vite] Internal server error: Failed to resolve import "flag-icons/css/flag-icons.css" from "src/main.ts". Does the file exist?
  File: /app/src/main.ts:13:7
  11 |  import sk from "./i18n/sk";
  12 |  import "./assets/main.css";
  13 |  import "flag-icons/css/flag-icons.css";
     |          ^

1.3 Critical File Verification (all exist)

• frontend/src/components/Logo.vue - Exists
• frontend/src/stores/vehicle.ts - Exists
• frontend/src/views/organization/CompanyOnboardingView.vue - Exists
• frontend/src/views/organization/CompanyGarageView.vue - Exists

1.4 Dependency Check

• frontend/package.json contains "flag-icons": "^7.5.0" - OK
• Container /app/node_modules/flag-icons: MISSING - FAIL

---

2. Root Cause Analysis

2.1 System Architecture

From docker-compose.yml:302-318:

sf_public_frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    volumes:
      - ./frontend:/app
      - /app/node_modules    # Anonymous volume isolates node_modules

From frontend/Dockerfile.dev:10:

RUN npm install   # Runs at BUILD time

2.2 Failure Mechanism

1. flag-icons was added to package.json (and package-lock.json updated)
2. The container was not rebuilt after the package.json change
3. The anonymous volume (/app/node_modules) preserved the old node_modules state
4. Since volumes take precedence over COPY/RUN instructions, npm install never ran
5. Vite couldn't find flag-icons/css/flag-icons.css at startup
6. Result: Internal server error → White screen

---

3. Fix Applied

3.1 Install Package Inside Container

docker exec sf_public_frontend npm install

Result: added 6 packages, changed 15 packages, and audited 281 packages

3.2 Restart Vite Dev Server

docker compose restart sf_public_frontend

Result: VITE v5.4.21 ready in 341 ms - running without errors

---

4. Secondary Observations (non-blocking)

4.1 ProfileView Address Display Issue

In frontend/src/views/ProfileView.vue:370-382, the read-only view uses:

<template v-if="person?.address?.address_zip || person?.address?.address_city">

This references a nested address object, but the new backend format sends address fields flat (e.g., person.address_zip, not person.address.address_zip). The edit mode correctly uses flat editForm.address_zip.

Recommendation: Change read-only display from person?.address?.address_* to person?.address_*.

4.2 Circular Dependency (safe)

• router/index.ts dynamically imports stores/auth in beforeEach guard
• stores/auth.ts statically imports router
• This is safe because the dynamic import runs only on navigation events, after the router is fully initialized.

---

5. Prevention Recommendations

5.1 Future Prevention

1. Rebuild trigger: When package.json changes, always rebuild the image:

   docker compose up -d --build sf_public_frontend
   

2. Pre-start npm install: Modify CMD to run npm install before starting:

   CMD npm install && npm run dev -- --host 0.0.0.0
   

3. Anonymous volume awareness: The anonymous volume preserves old node_modules. When package.json changes, rebuild the container, don't just restart.