TanStack Start가 Vite 기반 import protection을 기본 활성화하여 server와 client 코드 경계를 도구 수준에서 자동 적용한다

Context

Full-stack React 애플리케이션에서 server-only 코드(database query, 환경 변수)가 client bundle에 포함되는 문제가 빈번하게 발생한다. 기존 방식은 개발자 주의에만 의존하여 경계 위반이 런타임에되는 한계가 있었다.

Technical Solution

• Vite plugin이 개발 및 빌드 시 모든 import를 검증한다
• 파일명 패턴(server., client.)으로 기본 제한 규칙을 적용한다
• @tanstack/react-start/server-only 마커로 명시적 경계 지정이 가능하다
• vite.config.ts의 importProtection.client.specifiers로 커스텀 차단 규칙 추가가 가능하다
• 개발 환경에서는 mock mode(Proxy 치환 + warning log)로 허용하고, 빌드 시에는 error mode로 전체 import chain 진단을 출력한다

Impact

X 공지 포스트에서 590회 이상의 좋아요와 21건의 댓글을 받았다

Key Takeaway

import protection은 개발자 규율 대신 빌드 타임 검증을 통해 server와 client 경계 위반을 사전에 방지하는 설계이다