Next.js에 Clerk.dev 적용하기

soryeongk·2025년 8월 24일

준비하기

Next.js 환경의 프로젝트가 이미 있다는 가정 하에 작성했으며, 이 글을 작성하기 위한 프로젝트 환경은 다음과 같습니다.

# package.json
{
  "name": "soryeongk",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack",
    "start": "next start",
    "lint": "eslint"
  },
  "dependencies": {
    "@clerk/localizations": "^3.23.0",
    "@clerk/nextjs": "^6.31.4",
    "next": "15.5.0",
    "react": "19.1.0",
    "react-dom": "19.1.0"
  },
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "@tailwindcss/postcss": "^4",
    "tailwindcss": "^4",
    "eslint": "^9",
    "eslint-config-next": "15.5.0",
    "@eslint/eslintrc": "^3"
  }
}

기본 세팅은 Clerk 공식 문서(클릭)에서도 잘 설명하고 있으니, 함께 참고하시기 바랍니다.

Clerk.dev 세팅

로그인 후 create application 을 클릭해 프로젝트를 생성합니다.

회원가입 화면 커스터마이징

프로젝트 내에서 사용가능한 로그인 방법을 선택합니다. 저는 Email 또는 username으로 로그인할 수 있도록 했으며, 구글/애플/깃헙 로그인도 가능하도록 했습니다.

Email 인증은 아래 2개 방법을 사용할 수 있습니다.

DEFAULT 인증 코드(verification code) 발송: 첫 회원가입 시 1회성 코드를 보내기
인증 링크(verification link) 발송: 회원가입 시 10분 동안 사용 가능한 인증 링크를 보내기
- 링크는 동일 기기 동일 브라우저 내에서만 관리되기 때문에 PC에서 받은 링크를 모바일로 접속하는 것은 불가능합니다.

인증 링크 방법을 추가하는 것은 Configure > User & authentication 에서 가능한데, 막상 클릭하고 나면 작은 툴팁이 뜹니다.

"인증 링크의 전환률이 낮은 것으로 알려졌는데, 인증 코드를 쓰는게 어때?"

동일 기기와 브라우저에서만 관리된다는 점과 더불어 서비스 사용자의 플로우를 고려해 선택하는 것이 좋습니다.

아울러, 핸드폰 번호로 인증하는 것은 무료 플랜에서 사용할 수 없습니다. 또한, username은 글자수 제한(4~64자)이 있으며, 영어와 숫자 외의 글자 및 특수문자는 사용할 수 없습니다.

회원가입 옵션에 대한 상세한 내용은 Clerk 공식 문서(클릭)에서 확인할 수 있습니다.

환경 설정

프로젝트 생성 후에는 기본적으로 Development 모드입니다. 데스크탑 기준 좌측 상단의 Development를 클릭하면, 여러 환경을 세팅할 수 있습니다.

개발 모드에서 세팅을 모두 마친 후 릴리즈 직전에 운영환경을 만들면 자동으로 마이그레이션이 가능합니다. 하지만, 기본 세팅만 클론될 뿐, 웹훅을 비롯하여 보안이 중요한 설정은 클론되지 않아 production에서 다시 설정해야 합니다. 헷갈리는 일이 없도록 개발환경에서 세팅을 잘 기록하고, 테스트를 모두 완료한 후 production을 생성하고 그대로 옮기며 테스트하는 것이 필요합니다. 로그인 설정은 자주 바뀌지 않는 대신, 개발과 운영환경 간의 차이로 인한 사이드 이펙트는 발견하기 어려울 수 있습니다. 그러니 꼭 개발환경에서 설정과 테스트를 마친 후 꼼꼼히 클론해야 하며, 변경이 있는 경우에는 하나씩 적용하는 것을 추천합니다.

운영환경으로 clone하는 것과 관련한 자세한 내용은 Clerk 공식 문서(클릭)를 확인하시기 바랍니다.

Next.js 설정

개발 환경 세팅은 docs에서 친절하게 설명하고 있어 어려움이 없을거라 예상합니다. 프로젝트 생성 후 overview에서는 나의 개발 환경에 맞춘 세팅법을 상세히 확인할 수 있습니다.

Clerk sdk(@clerk/nextjs)를 설치한다.
.env에 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY와 CLERK_SECRET_KEY를 추가합니다. overview에 나온 것을 그대로 복사하시면 되고, configure > Developers > API Keys에서도 확인할 수 있습니다.
middelware.ts를 생성 또는 수정합니다. App Router 기준으로 app/ 폴더와 같은 위치에 있으면 되기 때문에, app 폴더가 최상단 폴더에서 접근할 수 있다면 최상단 폴더에, src 폴더 안에 있다면 그 안에 만들면 됩니다.이는 인증을 활성화하고 보호된 경로를 구성하는 데 사용됩니다. 예를 들어, App Router로 API를 생성해 사용한다면, Clerk의 로그인 과정이 필요없으므로 /api/route.ts를 인증 경로에서 제외하는 등의 일을 할 수 있습니다.
App Router 기준으로, 최상단의 layout.tsx에 <ClerkProvider />를 추가합니다. 서비스 전체에서 Clerk의 context가 잘 공유될 수 있도록 entry point에 Provider를 넣어 전체를 감싸는 것이 좋습니다. 참고로, overview에 있는 코드를 그대로 복사하면, 상단에 기본 header를 만들어줍니다.

Paths 설정

Application paths

fallback host를 지정하거나, 기본 홈화면 라우터를 지정할 수 있습니다. 가령, 로그인 후 /으로 가는 것이 아니라 /posts로 이동하고 싶다면, Home URL에 /posts를 입력하면 됩니다. 인증되지 않은 사용자의 redirect URL도 지정할 수 있습니다.

Component paths

첫 세팅 후 로그인 또는 회원가입을 누르면, 이상한 링크로 이동하는 것을 볼 수 있습니다. 이걸 Account Portal이라고 부릅니다. 만약 다른 페이지로 이동하는 것을 막고 싶다면, Component Paths에서 <SignIn /> SignUp /> 컴포넌트들을 띄울 라우터를 지정(ex. /sign-in, /sign-up)하면 됩니다.

Organization management

조직(Organization) 기능을 사용한다면, Organization management도 확인하세요.

개인 계정의 사용을 허용할지도 설정할 수 있습니다.

권한 관리 및 멤버 리밋도 지정할 수 있는데, 무료 플랜에서는 최대 5명까지만 허용하는 대신 조직의 수는 제한이 없습니다. Role 역시 기본으로 Member와 Admin이 있는데, 더 많은 역할을 부여하려면 결제가 필요합니다. 그 외에도 각 멤버가 할 수 있는 일에 대해서 지정할 수 있습니다.

Webhook 설정

Clerk에서 webhook 설정도 가능합니다. Configure > Developers > Webhooks에 trigger 조건과 endpoint를 추가하면 됩니다. 현재는 필요없게 되었지만, Next.js의 API Router를 사용해 간단한 작업을 할 수 있었습니다.

trigger 조건으로 쓰일 수 있는 항목은 Event Catalog에서 확인할 수 있습니다. 웹훅과 관련한 type sdk가 따로 없기 때문에, 내가 필요한 항목이 어디에 있는지 확인 후 사용해야 합니다. (당연함) 다행히 Event Catalog에서 각 항목의 타입을 상세하게 설명하고 있어 개발에 무리는 없습니다.