forked from baron/baron-sso
79 lines
3.5 KiB
Markdown
79 lines
3.5 KiB
Markdown
# 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
|
|
```
|