fix: README 백엔드 설정 안내가 무효(죽은 config 모듈) — 실제 동작 변수로 정정 + CRA 잔재 제거

[EricSeokgon]

수정 사유 Reason for modification

• 버그수정 Bug fixes
• 기능개선 Enhancements
• 기능추가 Adding features
• 기타 Others

문제 (재현)

README "2. 백엔드 프로젝트 설정" 절 — 신규 개발자가 가장 먼저 따라 하는 절 — 은 .env.development의 VITE_APP_EGOV_CONTEXT_URL에 백엔드 URL을 설정하라고 안내합니다. 그런데 이 변수는 아무 효과가 없습니다.

이 변수를 읽는 유일한 파일 src/config/index.js가 죽은 코드이기 때문입니다. src/config.js(파일)와 src/config/index.js(디렉터리)가 같은 4개 export를 동시에 정의하고 있고, Vite의 모듈 해석이 파일을 우선하므로 src/config.js만 로드됩니다.

실증 1 — vitest 프로브로 어느 모듈이 로드되는지 확인:

[PROBE] @/config      -> SERVER_URL = "/api"     (config.js 값)
[PROBE] ../src/config -> SERVER_URL = "/api"

실증 2 — README대로 설정된 상태(VITE_APP_EGOV_CONTEXT_URL=localhost:8080)로 개발 모드 빌드 후 번들 검사:

$ npx vite build --mode development
$ grep -o 'localhost:8080' dist/assets/*.js   → 결과 없음
$ grep -c '"/api"' dist/assets/*.js           → 1

번들에 localhost:8080이 전혀 없습니다. README 안내와 실제 동작이 불일치하고, README 자신도 뒤쪽 "컨테이너 배포" 절에서는 src/config.js·VITE_APP_API_BASE_URL을 올바르게 설명해 문서 안에서 앞뒤가 모순됩니다.

부수 위험: 죽은 config/index.js는 "http://"를 하드코딩하고 있어, 향후 누가 @/config/index로 직접 import하면 HTTPS 배포가 깨집니다.

수정 내용

1. 죽은 src/config/index.js 삭제 — 명시적 import 0건, 로드되지 않음을 실증
2. README 설정 절 정정 — 실제 동작하는 두 변수로 교체:
   • dev 서버에서 백엔드가 별도 호스트일 때: VITE_APP_API_PROXY_TARGET (vite.config.js의 프록시 대상, 기존에 미문서화 상태였음)
   • 빌드 산출물이 절대 URL로 직접 호출해야 할 때: VITE_APP_API_BASE_URL
   • 기본 흐름(백엔드 localhost:8080)은 추가 설정 없이 동작함을 명시
3. CRA 잔재 제거 (모두 Vite에서 무시됨):
   • package.json의 "proxy" 필드 (CRA 전용 — 실제 프록시는 vite.config.js에 있음)
   • .env.*의 NODE_PATH, GENERATE_SOURCEMAP (CRA 전용), VITE_EGOV_CONTEXT_URL(_APP 누락 오타로 아무도 읽지 않음)

검증

수정 후 전체 실행 (Node 20 / npm ci):

npx vitest run   → Test Files 9 passed (9) / Tests 44 passed (44)
npx vite build   → ✓ built (exit 0), 번들 API base "/api" 유지

• 삭제 파일은 로드되지 않던 코드이므로 런타임 동작 변화 없음
• package-lock.json은 건드리지 않았습니다 ("proxy"는 의존성 필드가 아니라 lock에 무관)

영향

• 신규 개발자가 README를 따라 하면 이제 실제로 동작합니다 (기존엔 무효 변수 설정 후 "왜 안 되지"를 겪는 흐름)
• 죽은 코드로 인한 미래 혼동(수정해도 반영 안 됨 / http 하드코딩) 제거
• 변경 범위: 5개 파일 +21 −30, 소스 코드 동작 변화 없음

[eGovFrameSupport]

표준프레임워크에 대한 지속적인 참여에
대단히 감사드립니다.

검토 결과 병합에 있어 방향성 자체는 올바르다고 판단됩니다.

죽은 모듈 삭제와 CRA 잔재 정리는 그대로 반영하면 되고, .env.production 의
VITE_APP_API_BASE_URL 도 실제 동작을 확인했습니다. 다만, 한 가지는 수정이 필요합니다.

• VITE_APP_API_PROXY_TARGET 은 .env.development 에서 동작하지 않습니다.

vite.config.js 는 이 값을 process.env 로 읽는데, config 파일이 평가되는 시점에는
.env 파일이 아직 로드되지 않습니다.

해당 내용은 다음 공식 문서에서도 확인 가능합니다.
https://vite.dev/config/#using-environment-variables-in-config

.env.development 에 기입하면 undefined, 셸 환경변수로 전달할 때만 값이 잡히는 것을 확인하였습니다.

그런데 README 와 .env.development 두 곳 모두 이 변수를 .env.development 에
설정할 수 있는 것으로 안내하고 있어, 본 PR 이 해결하려는 문제와 같은 형태의
불일치가 남게 됩니다.

해당 부분의 수정이 확인되면 병합을 진행하도록 하겠습니다.

[EricSeokgon]

정확한 지적 감사합니다. 말씀대로 vite.config.js는 config 평가 시점에 .env 파일이 아직 로드되지 않은 상태에서 process.env로 읽고 있었고, 그래서 .env.development에 적어도 undefined가 됐습니다. 제 PR이 .env.development에 설정 가능한 것처럼 안내하면서 고치려던 문제와 같은 형태의 불일치를 남긴 것이 맞습니다.

문서를 되돌리기보다, 안내가 실제로 동작하도록 vite.config.js에서 loadEnv로 명시 로드하는 방향으로 수정했습니다(링크 주신 공식 문서 방식). 방금 이 브랜치에 커밋했습니다.

import { defineConfig, loadEnv } from "vite";

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), "");
  return {
    // ...
    server: { proxy: { "/api": { target: env.VITE_APP_API_PROXY_TARGET || "http://localhost:8080", ... } } },
  };
});

검증 (Node 20):

• .env.development에 VITE_APP_API_PROXY_TARGET=http://10.20.30.40:9999를 넣고 loadEnv("development", cwd, "")로 읽으니 값이 정상적으로 잡힘(이전엔 undefined)
• npx vite build 통과, npx vitest run 44/44 유지

이제 README·.env.development 안내와 실제 동작이 일치합니다. 셸 환경변수도 그대로 병합되어 우선 적용됩니다. 혹시 config 변경 없이 문서만 "셸 환경변수 전용"으로 정정하는 편을 선호하시면 그 방향으로도 바로 바꾸겠습니다. 검토 감사합니다.

[eGovFrameSupport]

표준프레임워크에 대한 지속적인 참여에
대단히 감사드립니다.