make dev Vite HMR Policy

make dev는 로컬 개발 중 소스 변경이 즉시 화면에 반영되는 환경이어야 합니다. adminfront, devfront, orgfront는 make dev에서 production dist를 정적 서빙하지 않고 Vite dev server로 실행합니다.

Policy

make dev로 실행되는 React frontends는 Vite HMR 모드여야 합니다.
대상 서비스는 adminfront, devfront, orgfront입니다.
각 서비스는 Docker Compose에서 해당 Dockerfile의 dev target으로 빌드해야 합니다.
각 서비스의 working directory는 bind-mounted source path인 /workspace/<app>이어야 합니다.
각 서비스 command는 npm run dev -- --host 0.0.0.0 --port <port> 형태여야 합니다.
Docker bind mount 환경에서 파일 변경 감지가 누락되지 않도록 DEV_SERVER_WATCH_POLLING=true가 기본값이어야 합니다.
production image는 기존처럼 production target에서 build output dist를 serve_frontend_prod.mjs로 정적 서빙할 수 있습니다. 이 정책은 make dev runtime에만 적용합니다.

Current Ports

AdminFront: http://localhost:5173
DevFront: http://localhost:5174
OrgFront: http://localhost:5175

Required Structure

Each React frontend Dockerfile must keep these stages:

deps: install workspace dependencies.
dev: run Vite dev server from /workspace/<app>.
build: run production build.
production: serve built dist with the static server.

docker-compose.yaml must select target: dev for the three React frontends. This prevents make dev from accidentally serving stale /app/dist output.

Regression Guard

The policy is checked by:

test/frontend_dev_bind_mount_policy_test.sh
test/playwright_frontend_runtime_policy_test.sh

The test verifies that:

source directories are bind-mounted into /workspace/<app>;
node_modules stays in container volumes;
each React frontend uses target: dev;
each React frontend runs npm run dev;
each React frontend enables polling watch by default;
serve_frontend_prod.mjs is not used by the Compose dev service;
Dockerfiles keep separate dev, build, and production stages.

If this test fails, do not work around it by refreshing the browser or rebuilding manually. Fix the Compose/Dockerfile runtime so make dev remains a true HMR development mode.

Playwright Runtime Policy

Local Playwright tests should use Vite dev servers by default. This keeps local E2E feedback aligned with make dev and avoids testing stale production dist output while actively editing frontend code.

Gitea Actions and other CI runs should use build output through Vite preview. This validates production bundle behavior before merge.

Required behavior:

Local default:
- AdminFront uses Vite dev server on port 5173.
- DevFront uses Vite dev server on port 5174.
- OrgFront uses Vite dev server on port 5175.
CI or explicit preview mode:
- CI=true or PLAYWRIGHT_USE_PREVIEW=true switches React frontend Playwright web servers to build + preview.
Existing running server mode:
- BASE_URL can be used for AdminFront and OrgFront.
- PLAYWRIGHT_BASE_URL or BASE_URL can be used for DevFront.
- PLAYWRIGHT_SKIP_WEBSERVER=true disables DevFront's managed web server.

Use explicit preview locally only when testing production bundle behavior:

PLAYWRIGHT_USE_PREVIEW=true npm --prefix adminfront test
PLAYWRIGHT_USE_PREVIEW=true npm --prefix devfront test
PLAYWRIGHT_USE_PREVIEW=true npm --prefix orgfront test

3.5 KiB Raw Blame History