Rails 애플리케이션에 SSR을 설정하기 위한 주요 단계와 발생 가능한 문제 해결 방안은 다음과 같습니다.
1. SSR 엔트리 포인트 생성
frontend/ssr/SSR.js(또는SSR.tsx) 파일을 생성하여 SSR을 위한 새로운 엔트리 포인트를 정의합니다.- 이 파일은 브라우저가 아닌 Node.js 환경에서 실행되며, Inertia 앱을 생성하고 React 서버 DOM 렌더링을 통해 페이지를 문자열로 변환하여 HTML을 생성합니다.
- 주의사항: 기존 클라이언트 측 초기화 파일에서 사용하는 고유한 설정(예: TanStack Query)은 SSR 엔트리 포인트에도 동일하게 적용해야 합니다.
location.pathname과 같은 브라우저 전용 API 사용은 SSR 환경에서 문제를 일으킬 수 있으므로 주의해야 합니다.
2. Vite 설정 업데이트
config/vite.json파일에ssr_build_enabled속성을true로 추가하여 Vite가 SSR 빌드를 처리하도록 설정합니다.vite.config.js파일 내ssr옵션에 대한 명확한 설정이 필요하며, 특히 프로덕션 환경에서만 활성화할지 여부를 고려해야 합니다.
3. SSR 번들 빌드 및 실행
vite build SSR명령어를 사용하여 SSR 번들을 빌드합니다.vite SSR명령어를 실행하여 Inertia SSR 서버를 시작합니다.
4. 주요 디버깅 시나리오 및 해결책
- 엔트리 포인트 경로 오류:
frontend/entrypoints가 아닌frontend/ssr경로에SSR.js파일을 생성해야 합니다. - 파일 확장자 불일치: JSX/TSX 컴포넌트를 사용하는 경우, 엔트리 포인트 파일 확장자를
.js대신.jsx또는.tsx로 지정해야 합니다. (예:SSR.tsx) 이 오류는 “Cannot read properties of undefined reading default”와 같은 모호한 메시지로 나타날 수 있습니다. - 의존성 버전 문제: Inertia.js, React, Vite 플러그인 등의 버전이 최신인지 확인하고 업데이트가 필요한 경우 진행합니다.
- 클라이언트 하이드레이션: SSR이 완료된 후 클라이언트 측 JavaScript가 페이지를 “활성화”하도록
createRoot대신hydrateRoot를 사용하도록 메인 클라이언트 엔트리 포인트를 수정합니다.
5. 배포 및 활용 고려사항
- 프로덕션 환경에서는 클라이언트 및 서버 측 번들을 모두 빌드하고, SSR 서버를 백그라운드 프로세스로 실행해야 합니다. 이는 Docker 이미지 등 배포 환경에 추가적인 복잡성을 더할 수 있습니다.
- SSR의 실제 필요성에 대한 고민이 필요합니다. 로그인 기반의 SaaS 애플리케이션에서는 SEO의 중요성이 낮으므로 SSR의 이점이 제한적일 수 있습니다. 반면, 마케팅 페이지나 공개 디렉토리와 같이 모든 사용자에게 노출되어야 하는 페이지에는 SSR이 매우 유용합니다.