일상/IT

Clerk로 Next.js 앱에 소셜 로그인, 프로필, 보안 페이지 완성하는 방법

얇은생각 2025. 7. 9. 19:30
반응형

5분 안에 Next.js 앱에 User Authentication 시스템을 완성하는 초간단 가이드

한눈에 보기: Email 검증, 소셜 OAuth, 비밀번호 재설정 같은 반복 작업에 시간을 낭비하지 마세요. 이 글은 Clerk SDK를 Next.js 프로젝트에 꽂아 넣고, 로그인·회원가입·소셜 로그인·프로필 관리·보호된 Dashboard까지 ‘단 5분’ 만에 구현하는 과정을 보여줍니다. 속도는 올리고, 아이디어 실현까지 남은 거리도 확 줄이세요.

 


 

1. 사이드 프로젝트가 중도 포기되는 이유 {#why-quit}

 

1. 사이드 프로젝트가 중도 포기되는 이유 {#why-quit}

개발자라면 누구나 하드 디스크 어딘가에 ‘두고만 본’ repo 하나쯤 있습니다. 초반엔 번쩍이는 아이디어에 설렜지만, 정작 npm init 이후엔 의욕이 시들해지죠. 왜 그럴까요? 대개는 ‘신나지 않는 잡일(boilerplate)’이 진을 빼기 때문입니다.

 

2. Inspiration보다 Momentum이 중요한 까닭 {#momentum}

아이디어는 유통기한이 짧습니다. 초반에 빠르게 달리지 못하면 ‘머지나 잔업’에 눌려 서서히 식어버리죠. 중요한 건 헐떡이며 달리는 속도가 아니라, 마찰 없는 흐름(Momentum) 입니다.

 

3. 지루하지만 필수적인 기능의 숨은 비용 {#boring}

 

3. 지루하지만 필수적인 기능의 숨은 비용 {#boring}

로그인 폼, OAuth 세팅, 프로필 페이지, TOS 체크박스… 앱을 만들다 보면 거의 필수지만 재미는 1g도 없는 작업들이 줄지어 등장합니다.

  • Email 인증 코드 전송·재전송 로직
  • Google·GitHub·SMS OAuth 춤사위
  • Avatar 업로드 & Storage 연결
  • Account 관리 UI
  • Brute-force 공격 대비 Rate-limiting

 

손수 만들다 보면 주중 밤, 주말 아침이 순식간에 사라지고, 프로젝트는 Trello 한 칸에서 더 이상 움직이지 않습니다.

 

4. Clerk가 가져다주는 5분의 기적 {#clerk}

 

4. Clerk가 가져다주는 5분의 기적 {#clerk}

Clerk는 React 생태계를 겨냥한 User Management 플랫폼입니다. SDK 하나만 추가하면 아래 기능이 한방에 준비됩니다.

  • Email/Password · Phone · Magic-link Sign-up
  • Google, GitHub 등 다양한 Social Provider
  • SignIn, SignUp, UserButton 같은 완성형 React 컴포넌트
  • Dark mode 지원 Theme
  • Middleware 기반 Route 보호 헬퍼
  • 10,000 MAU까지 무료인 넉넉한 Free tier

자, 이제 속도를 체감해 봅시다.

 


 

5. Step 1 – Installation {#install}

  1. 계정 생성: clerk.com으로 이동해 Sign up.
  2. 프로젝트 이름 짓기: 예시로 my-awesome-idea 입력. Auth 방법은 Email, Phone, Google, GitHub만 체크해 가볍게 시작합니다.
  3. SDK 설치: 대시보드에서 표시된 커맨드 복사 후 프로젝트에 실행.
  4. npm install @clerk/nextjs
  5. 환경 변수 세팅: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY와 CLERK_SECRET_KEY 두 값을 .env.local에 붙여넣기.
  6. middleware 배선: middleware.ts 파일을 만들고, 문서에 있는 스니펫을 복붙. 정적 파일은 건너뛰고 /api/* 포함 나머지 요청을 체크합니다.
  7. 취향이라면 theme 추가:다크모드를 사랑한다면 필수.
  8. npm install @clerk/themes

 

여기까지 60초도 채 쓰지 않았습니다.

 

6. Step 2 – Setup & 기본 배치 {#setup}

app/layout.tsx 최상단에 <ClerkProvider>로 감싸주세요:

<ClerkProvider appearance={{ baseTheme: dark }}>
  {children}
</ClerkProvider>

 

다음은 헤더를 간단히 만들어봅니다:

<header>
  <SignedOut>
    <SignInButton />
    <SignUpButton />
  </SignedOut>
  <SignedIn>
    <UserButton />
  </SignedIn>
</header>

 

개발 서버를 띄우면, 비로그인 상태에선 Sign in / Sign up 버튼만 보입니다. Sign up → GitHub를 눌러 OAuth 흐름을 체험하면, 전화번호 인증까지 처리된 뒤 홈으로 되돌아오고, 헤더엔 동그란 UserButton이 등장합니다. 클릭하면 Avatar, 사용자명, ‘Manage account’, ‘Sign out’ 링크까지 한눈에.

 

방금 작업이 커피 한 잔 내리기보다 빠릅니다.

 

7. Step 3 – 스타일 커스터마이징 {#style}

브랜드 컬러를 바꾸고 싶다면?

  1. 대시보드 → Configure → Account Portal → Customization
  2. Primary color를 내 팔레트로 교체. 저는 보라 대신 에메랄드를 선택했어요.
  3. 저장 후 local 앱 새로고침 → 색상이 즉시 반영됩니다.

 

Legal 체크박스도 원클릭

SaaS라면 Terms of Service와 Privacy Policy 동의를 받아야겠죠.

  • 대시보드 → Legal 탭으로 이동
  • Require agreement 스위치 ON
  • TOS, Privacy 페이지 URL 입력

 

이제 로그인 폼에 체크박스가 생깁니다. 심지어 소셜 로그인 리다이렉트 후에도 동의를 먼저 받아요. 코드 한 줄 없이 컴플라이언스 해결.

 

8. Step 4 – 라우트 보호하기 {#guard}

인증된 사용자만 접근 가능한 /dashboard 페이지를 만든다고 가정해 봅시다.

  • 페이지 생성: app/dashboard/page.tsx.
  • matcher 작성:
// middleware.ts
import { authMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isProtected = createRouteMatcher([
  "/dashboard(.*)", // /dashboard 이하 모든 서브 라우트 보호
]);

export default authMiddleware({
  publicRoutes: (path) => !isProtected(path),
});
  • 로그아웃 상태로 /dashboard에 접근하면 Sign-in으로 리다이렉트, 로그인 후엔 문제없이 입장.

 

9. 보너스 – 유저에게 인사하기 {#greet}

Dashboard에 개인 인사말을 띄우고 싶다면:

import { currentUser } from "@clerk/nextjs";

export default async function Dashboard() {
  const user = await currentUser();
  return <h1>{user?.firstName ?? "친구"}님, 반가워요!</h1>;
}

 

고작 한 줄로 맞춤 메시지 완성.

 

10. 잠이 오는 가격 정책 {#price}

Clerk Free tier는 10,000 MAU까지 공짜. 그 이후부턴 월 1인당 $0.02만 부과됩니다. 여기서 Active란 ‘해당 월에 실제 로그인한 사용자’를 의미합니다. 계정만 만들고 돌아오지 않으면 요금이 붙지 않아요.

 

11. 더 깊이 파고들 기능 {#extras}

오늘은 맛만 봤지만 Clerk에는 이외에도

  • Brute-force 공격 차단
  • Bot 감지
  • Organization 관리(멀티 테넌트 SaaS에 유용)
  • Disposable email 탐지
  • Headless API & Hooks
  • White-label: Clerk 로고 제거, Modal 형태 Embedding, Email 템플릿 커스텀 등

 

12. 마무리 – 결국 완성하는 사람이 되려면 {#wrap}

5분 만에 이만큼의 Product Surface를 열 수 있다는 건 상상 이상입니다. Auth를 Clerk에 맡기면 진짜 혁신이 필요했던 영역에 집중할 수 있죠. 아이디어를 끝까지 끌고 가려면, 마찰을 줄이고 흐름을 살려야 합니다.

지금 바로 속도를 올리고 싶다면? Clerk 무료 계정 만들기 버튼을 눌러 Next.js 프로젝트에 날개를 달아보세요.

 

반응형