인증 스타터 만들기: Next.js, PostgreSQL, Prisma, 그리고 NextAuth 통합에서 얻은 교훈

Source: Dev.to

소개

새로운 웹 프로젝트를 시작할 때, 사용자 인증을 설정하는 것이 상당한 초기 마찰처럼 느껴질 수 있습니다. 사용자 데이터를 관리하고, 라우트를 보호하며, 다양한 로그인 방식을 처리하고, 모든 것을 타입‑안전하게 유지하는 것이 일반적인 과제입니다. 이를 해결하기 위해 저는 Next.js 인증 스타터 앱을 만들었으며, 이 앱은 이러한 복잡성을 기본 제공으로 처리하면서 향후 프로젝트를 위한 견고한 기반을 제공합니다.

Core Technologies

기능

• 사용자 폼: 로그인, 회원가입, 이메일 인증, 비밀번호 업데이트 및 비밀번호 재설정 페이지. 이메일/비밀번호와 소셜 로그인(Google, GitHub)을 모두 지원합니다.
• 보호된 라우트: middleware.ts가 사용자 세션을 확인한 후 보호된 페이지(예: /settings)에 접근을 허용합니다.
• 이메일 인증 및 비밀번호 재설정: Resend를 통해 보안 토큰 생성 및 이메일 전송을 수행합니다.
• 데이터 처리: 변이를 위한 actions/와 읽기 전용 작업을 위한 data/를 구분하여 책임을 분리합니다.

프로젝트 레이아웃

app/                # 라우트 정의 (공개 및 보호된)
actions/            # DB 변이를 위한 서버 액션
data/               # 읽기 전용 데이터 조회 함수
components/         # 재사용 가능한 UI 요소
lib/                # 일반 유틸리티 및 헬퍼
prisma/             # Prisma 스키마 및 생성된 클라이언트
schemas/            # Zod 검증 스키마
middleware.ts       # 라우트 보호 로직
auth.config.ts      # NextAuth 설정 (프로바이더, 콜백)

예시: NextAuth 설정 (auth.config.ts)

import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";
import GitHubProvider from "next-auth/providers/github";

export const authOptions = {
  providers: [
    GoogleProvider({ clientId: process.env.GOOGLE_ID!, clientSecret: process.env.GOOGLE_SECRET! }),
    GitHubProvider({ clientId: process.env.GITHUB_ID!, clientSecret: process.env.GITHUB_SECRET! }),
  ],
  callbacks: {
    async session({ session, token }) {
      session.user.id = token.sub;
      return session;
    },
  },
};

export default NextAuth(authOptions);

예시: Zod 스키마 (schemas/login.ts)

import { z } from "zod";

export const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

요약

• Zod를 사용한 명시적 검증: 오류를 조기에 포착하고 폼 입력에 대해 명확한 피드백을 제공합니다.
• 관심사의 분리: actions/(변경)와 data/(조회)를 구분함으로써 서버‑측 로직을 단순화하고 유지 보수성을 향상시킵니다.
• 데이터 가져오기 유연성: 이 스타터는 TanStack Query, useSWR 또는 기타 어떤 가져오기 전략과도 함께 사용할 수 있습니다.

고려한 대안

• ORMs: Neon을 탐색했지만, Prisma의 TypeScript 타입‑안전성과 개발자 경험이 스타터 키트에 더 적합했습니다.
• Email Services: 다양한 옵션이 존재합니다; Resend는 직관적인 API 때문에 선택했지만, 다른 제공자로 교체하는 것은 간단합니다.

결론

이 Next.js 인증 스타터는 널리 인정받는 도구들을 결합하여 일반적인 인증 과제를 해결합니다. Next.js 14와 함께 사용자 인증이 필요한 애플리케이션을 위한 신뢰할 수 있는 시작점을 제공합니다. 저장소를 탐색하고, 컴포넌트를 조정하거나, 개선 사항을 제안해 주세요.

Next.js Auth Starter