환경별 인증 Provider 조건부 분기로 런타임 오류 방어
목차
Clerk 연동을 레이아웃 루트에 붙이면서, 조건부 Provider 래핑 패턴을 선택한 날.
왜 조건부 ClerkProvider인가
Next.js App Router 구조에서 인증 Provider를 루트 layout.tsx에 올리는 건 거의 필수 수순이다. 그런데 Clerk를 단순하게 <ClerkProvider>로 전체를 감싸버리면 문제가 생기는 시나리오가 꽤 있다.
대표적으로 — 퍼블릭 마케팅 페이지, 랜딩, 또는 인증이 아예 필요 없는 구간에서도 Clerk SDK가 초기화되고 네트워크 요청이 나간다. 환경 변수(NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY)가 없는 환경(로컬 테스트 빌드, CI, 일부 스테이징)에서는 아예 런타임 에러가 터진다. 이게 꽤 고약한 게, 빌드 타임에는 조용히 넘어가다가 런타임에서 터지는 패턴이라 처음 마주치면 당황스럽다.
그래서 선택한 게 조건부 ClerkProvider 래핑이다.
// apps/web/src/app/layout.tsx (패턴 예시)
const isClerkEnabled = !!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY;
export default function RootLayout({ children }: { children: React.ReactNode }) {
if (isClerkEnabled) {
return (
<html lang="ko">
<body>
<ClerkProvider>{children}</ClerkProvider>
</body>
</html>
);
}
return (
<html lang="ko">
<body>{children}</body>
</html>
);
}
환경 변수 존재 여부로 Provider 자체를 분기하는 방식. 단순하지만 효과는 확실하다.
변경 파일 두 개가 말해주는 것
| 파일 | 역할 | 이번 변경의 의미 |
|---|---|---|
apps/web/src/app/layout.tsx |
앱 전체 루트 레이아웃 | Clerk Provider wire-up + 조건부 분기 추가 |
md/DAILY/2026-05-25.md |
데일리 로그 | 작업 배경/의도/이슈 기록 |
layout.tsx 하나만 바뀐 게 아니라 데일리 마크다운도 같이 커밋됐다는 건, 이 작업을 그냥 "코드 추가"로 끝내지 않고 왜 이 선택을 했는지 남겨뒀다는 의미다. 팀 운영 관점에서 이게 생각보다 중요하다. 나중에 "왜 단순 ClerkProvider 안 쓰고 조건부로 했어요?"라는 질문이 들어왔을 때, PR 코멘트나 데일리 로그에 맥락이 있으면 설명 비용이 확 줄어든다.
코드리뷰할 때도 마찬가지인데, 변경 이유가 코드 바깥에 있을 때는 커밋 메시지나 PR description에 그 맥락을 짧게라도 남기는 습관이 팀 전체의 온보딩 비용을 낮춘다. feat(auth): wire Clerk with conditional ClerkProvider라는 커밋 메시지 자체도 "conditional"이라는 단어를 명시적으로 넣어서 "그냥 붙인 게 아님"을 표현하고 있다.
루트 레이아웃에 Provider 올릴 때 체크리스트
App Router에서 인증 Provider를 루트에 붙이는 작업은 단순해 보여도 놓치기 쉬운 포인트가 있다.
- 환경 변수 guard: Provider가 키 없이 초기화되는 상황 방어
- SSR/SSG 호환: Clerk 같은 클라이언트 의존 Provider가 서버 컴포넌트 트리와 충돌하는지 확인
- middleware 연동:
middleware.ts에서 Clerk의authMiddleware또는clerkMiddleware설정이 Provider와 정합성 맞는지 - publicRoutes 정의: Provider 수준에서 퍼블릭 라우트 처리할지, middleware 레벨에서 할지 팀 컨벤션 정리
이번 작업은 Provider wire-up 자체가 목표였고, 조건부 분기로 환경 간 안전성을 확보했다. middleware 연동이나 퍼블릭 라우트 정책은 아마 다음 스텝에서 따라올 작업들일 것이다. 인증 레이어는 한 번에 다 올리려다 꼬이는 케이스가 많아서, 이렇게 Provider 연결 → 미들웨어 → 라우트 보호 순서로 단계 나눠서 가는 게 맞는 접근이다.
데일리 로그를 코드와 같이 커밋하는 습관, 계속 유지하는 게 좋겠다.
다음
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.