Next.js 프로젝트를 CRA 환경으로 마이그레이션하며 겪은 기술 부채와 극복기

Next.js 프로젝트를 CRA 환경으로 마이그레이션하며 겪은 기술 부채와 극복기

핵심 기술

본 콘텐츠는 Next.js 기반의 외부 프로젝트를 기존 CRA(Create React App) 환경으로 통합하는 과정에서 발생한 다양한 기술적 난관들을 상세히 기술하며, TypeScript 버전 호환성, API 타입 정의, 빌드 설정, 모듈 폴리필, 렌더링 방식 차이, 스타일링, 라이브러리 호환성, 그리고 복잡한 상태 관리 라이브러리(XState) 적용 등 실제 개발 현장에서 마주할 수 있는 문제점과 해결 방안을 공유합니다. 기술 부채를 알면서도 빠른 런칭을 위해 마이그레이션을 강행한 경험을 바탕으로, 현실적인 개발 의사결정과 그에 따른 기술적 과제를 중심으로 내용을 전개합니다.

기술적 세부사항

• TypeScript 버전 충돌 및 해결: CRA의 react-scripts 버전이 TypeScript 5.0 버전을 지원하지 않아, 지원 범위에 맞는 4.9.5 버전으로 다운그레이드했습니다. 이후 Web MIDI API 타입 정의를 위해 TypeScript 5 버전의 webmidi.d.ts 파일을 수동으로 프로젝트에 추가했습니다.
• tsconfig.json 설정: 외부 프로젝트의 tsconfig.json target이 ES5로 설정되어 ES6 스프레드 연산자 사용 시 컴파일 에러가 발생했습니다. target을 직접 변경하는 대신 downlevelIteration: true; 옵션을 추가하여 ES5 환경에서도 ES6 이터레이션 문법을 안전하게 변환했습니다. 또한, CRA에서 tsconfig.json의 paths alias 설정을 무시하는 문제를 CRACO를 사용하여 오버라이드했습니다.
• Node.js 모듈 브라우저 폴리필: js-synthesizer 라이브러리가 Node.js 전용 stream 모듈을 필요로 하는 문제를 stream-browserify를 설치하고 craco.config.js의 Webpack 설정에 fallback 옵션을 추가하여 해결했습니다.
• 렌더링 방식 차이 대응: Next.js의 SSR과 CRA의 CSR 환경 차이로 인해 VexFlow 라이브러리의 getBoundingBox 함수 호출 시 DOM 렌더링 완료 전 발생하는 에러에 옵셔널 체이닝(?.)을 적용하여 안전하게 처리했습니다.
• 스타일링 통합: 기존 스타일 시트와의 충돌 및 사이드 이펙트를 방지하기 위해 OverrideOtherPrjName.scss 파일을 별도로 생성하여 스타일을 추가했습니다.
• 라이브러리 호환성 및 의존성 관리: 신규 기능에 사용되는 라이브러리 설치 시 프레임워크 호환성, 의존성 라이브러리 버전, 각 라이브러리 간 호환성을 신중하게 체크했습니다.
• 비공개 패키지 연동: npm으로 설치되지 않는 비공개 패키지를 npm 모듈에서 직접 포함하는 방식으로 전환했습니다.
• XState 상태 관리: 복잡한 상태 관리를 위한 XState 라이브러리의 구조 파악에 어려움을 겪었으나, 데드라인 내에서의 완벽한 이해 대신 수정 목적을 명확히 하여 주석을 상세하게 추가하는 방식으로 대응했습니다.
• 모듈 구조 및 코드 통합: 필요한 기능의 하위 컴포넌트부터 시작하여 상위로 거슬러 올라가는 방식으로 코드를 선별적으로 가져와 프로젝트 복잡도를 낮췄습니다. 외부 모듈 위치는 기존 폴더 구조에 맞추되, src/OtherPrjName/과 같이 별도 하위 폴더로 구분하여 관리했습니다.

개발 임팩트

• 빠른 런칭: 사업적 요구사항에 맞춰 기술적 이상과 현실 사이의 균형을 통해 빠른 기능 런칭을 달성했습니다.
• 기술 부채의 인식 및 관리: 마이그레이션 과정에서 발생하는 기술 부채의 중요성을 체감하고, 향후 Vite와 같은 모던 도구로의 전환 및 코드 리팩토링의 필요성을 제기합니다.
• 문제 해결 능력 향상: 다양한 기술적 난관을 직접 해결하며 문제 해결 능력을 함양하고, 레거시 시스템 통합 경험을 축적했습니다.

커뮤니티 반응

원문에서 커뮤니티 반응에 대한 직접적인 언급은 없으나, CRACO, TypeScript, XState와 같은 기술들은 개발자 커뮤니티에서 활발하게 논의되고 있으며, 본 콘텐츠에서 제시된 문제점들은 유사한 상황에 직면한 많은 개발자들이 공감할 만한 내용입니다.

톤앤매너

콘텐츠는 실제 프로젝트 수행 경험을 바탕으로 한 솔직하고 현실적인 개발자의 목소리를 담고 있습니다. 전문적인 기술 용어와 함께 경험에서 우러나오는 인사이트를 전달하며, 문제 해결 과정의 어려움과 성취감을 균형 있게 표현하고 있습니다. 개발자를 위한 실질적인 가이드 및 경험 공유의 톤앤매너를 유지하고 있습니다.