RAG 기반 문서 검색 시스템 - 3(Next.js 초기화 및 인증 연동)

개요

앞선 글에서는 RAG 기반 문서 검색 시스템의 핵심 인프라를 어떻게 Terraform과 Helm으로 자동화하고, 보안 및 운영 관점에서 완성도 높은 클라우드 환경을 구성했는지를 다뤘다.  이번 글에서는 본격적인 프론트엔드 세팅 작업 중, Next.js 초기화 및 인증 연동에 대해 다룬다. 해당 태스크는 초기 프론트엔드 구조 수립부터 인증, 접근성, 모바일 대응까지 통합적으로 구성한 작업이다.

전체 작업 흐름

Next.js 초기화 및 인증 연동작업은 다음과 같은 7단계로 구성된다.

1. Next.js 프로젝트 초기화 및 폴더 구조 수립
2. Tailwind CSS, SWR 통합
3. React Context 기반 글로벌 인증 상태관리 구현
4. OAuth2.0 기반 소셜 로그인 연동
5. JWT 자동 전송 및 보호 라우팅 구성
6. 모바일 반응형 및 WCAG 2.1 AA 접근성 적용
7. MCP 연동 및 작업 문서화

단계별 작업 상세

1. 프로젝트 구조화 (Next.js + TypeScript)

• Next.js 기반 프로젝트 생성 및 TypeScript 적용
• 폴더 구조: src, components, contexts, hooks, services, types 등 명확한 역할 분리
• .prettierrc, .eslintrc 등 개발 표준 설정
• README.md 문서화 및 초기 커밋 완료

결과: 로컬 및 CI 환경에서 정상 실행, 구조 확장성 확보

2. Tailwind CSS & SWR 통합

• Tailwind CSS 설치 및 글로벌 스타일 구성
• SWR 설치 및 클라이언트 데이터 패칭 예제 구현
• 스타일 및 패칭 관련 에러 테스트 완료

결과: 스타일과 데이터 패칭 동작 모두 정상

3. 글로벌 인증 상태관리 (Context API)

• src/contexts/AuthContext.tsx에 인증 Provider 구현
• useReducer 기반 상태 관리
• localStorage와 연동하여 새로고침 시 상태 유지
• _app.tsx에 AuthProvider 적용

결과: JWT 및 사용자 정보가 전역 Context로 관리됨

4. 소셜 로그인 및 인증 플로우

• SocialLoginButtons.tsx로 Google, Github 로그인 버튼 UI 구현
• /auth/callback 경로에서 JWT 발급 및 Context 저장 처리
• OAuth2 인증 성공 시 사용자 정보 저장

결과: 소셜 로그인 정상 동작, JWT 저장/관리 완료

5. JWT 자동 전송 및 보호 라우팅

• Axios 인터셉터로 모든 요청에 JWT 자동 포함
• withAuth.tsx에서 보호 라우팅 HOC 구현
• 토큰 만료 시 자동 로그아웃 및 리다이렉트 처리

결과: 인증 없는 접근 차단, 보안성 향상

6. 모바일 대응 및 웹 접근성

• Tailwind 유틸리티(sm:~)를 활용한 모바일 대응
• aria-*, role 속성, 시맨틱 태그로 접근성 강화
• 자동화 도구를 활용한 접근성 점검 완료

결과: 다양한 기기 및 사용자 환경에서 UI 일관성 확보

7. 문서화 및 MCP 연동

• 작업 내역을 README 및 Notion MCP에 자동 반영
• 팀 온보딩 및 유지보수를 고려한 문서화 진행

결과: 작업 이력 추적 가능, 협업 기반 마련

 

8. 깃허브 업로드 에러 및 해결 회고

작업을 마친 뒤 GitHub에 작업 결과를 업로드하는 과정에서, 예상치 못한 대용량 파일 에러(100MB 초과)로 인해 push가 거부되는 문제가 발생했다. 해당 사례를 통해 얻은 인사이트와 해결 과정을 기록한다.

문제 상황

• 브랜치: develop
• git push 시 아래 에러 발생:

File ... is 129.57 MB; this exceeds GitHub's file size limit of 100.00 MB

• 문제 원인:
  • node_modules 내부 대용량 바이너리(next-swc.win32-x64-msvc.node)가 포함됨
  • .gitignore 설정 누락으로 인해 node_modules, .next 등도 커밋됨

원인 분석

항목설명

📦 npm install 후	node_modules 내 바이너리 자동 생성
📄 .gitignore 누락	불필요 디렉토리까지 커밋 대상 포함
⌨️ git add .	전체 파일 스테이징, 대용량 포함

해결 과정

1. .gitignore에 아래 항목 추가:

   node_modules/
   .next/
   

2. Git 캐시에서 불필요 파일 제거:

   git rm -r --cached node_modules .next
   

3. 커밋 및 push 시도 → 실패 (기록에 이미 포함됨)
4. BFG Repo-Cleaner로 Git 기록 정리:

   java -jar bfg.jar --delete-files '*next-swc.win32-x64-msvc.node'
   git reflog expire --expire=now --all
   git gc --prune=now --aggressive
   

5. 정리 후 강제 push:

   git push origin develop --force
   

6. 정상적으로 업로드 완료

회고 및 교훈

• .gitignore는 프로젝트 초기부터 신경 쓸 것
• 빌드 산출물, 외부 라이브러리는 절대 커밋하지 말 것
• Git은 커밋된 이력까지 남기므로 필요 시 BFG로 정리
• push 에러 메시지를 무시하지 말고 정확히 읽고 검색할 것

관련 명령어 요약

명령설명

git rm -r --cached	Git 캐시에서만 파일 제거
bfg.jar --delete-files	Git 히스토리에서 특정 파일 삭제
git gc --prune=now --aggressive	가비지 수집 및 용량 정리
git push --force	강제 푸시 (주의 필요)

이 경험을 통해 Git 기록 관리의 중요성을 체감했다. 앞으로는 커밋 전 확인 → .gitignore 관리 → push 전 점검을 개발 습관으로 삼는다.

 

T-003태스크의 서브태스크

노션 링크 : https://www.notion.so/RAG_UI_-T-003-23072b9b162381a5bb44e708ff6e80cb

 

관련 용어 정리

용어설명

Next.js	React 기반 프레임워크. SSR과 정적 페이지 생성을 지원
TypeScript	정적 타입을 제공하는 JavaScript 상위 집합
SWR	React용 데이터 패칭 라이브러리. stale-while-revalidate 전략 사용
OAuth2.0	외부 소셜 계정 기반 인증 프로토콜
JWT	JSON Web Token. 인증 및 권한 부여를 위한 토큰
Context API	React 컴포넌트 간 전역 상태 공유를 위한 기능
Axios 인터셉터	요청 전/후에 토큰 자동 삽입 또는 오류 처리를 수행하는 기능
WCAG 2.1	웹 콘텐츠 접근성 가이드라인. AA는 중간 수준의 접근성 등급
MCP	Meta Collaboration Platform. 문서 및 작업 기록 자동화 도구

 

마무리

이번 글에서는 Next.js 기반 프론트엔드 구조를 수립하고, 인증 및 사용자 경험을 강화하기 위한 세부 작업을 정리했다. 다음 글에서는 인증/권한/사용자/ORM 연동을 중심으로 이어서 다룰 예정이다.