# 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:

```sh
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:

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