🚀 Next.js + Firebase로 만드는 풀스택 웹앱 실전 프로젝트

🎯 목표

1. Firebase Admin SDK 초기화 (서버 전용)
2. 세션쿠키 방식 로그인(클라이언트 ID 토큰 → 서버 세션 쿠키)
3. Server Actions에서 UID 검증 후 Firestore 조작
4. FormData 검증과 에러 핸들링 패턴

0) 환경 변수 준비(.env.local)

Admin SDK는 서버 전용이므로 “클라이언트에 노출되면 안 됩니다”.

NEXT_PUBLIC_ 접두사 사용 금지.

FIREBASE_ADMIN_PROJECT_ID=your-project-id
FIREBASE_ADMIN_CLIENT_EMAIL=firebase-adminsdk-xxxx@your-project-id.iam.gserviceaccount.com
# 멀티라인 키의 \n 을 실제 개행으로 치환해서 쓰는 편이 가장 안전합니다.
FIREBASE_ADMIN_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nABC...XYZ\n-----END PRIVATE KEY-----\n"

# 세션쿠키 수명(일 기준). 예: 7일
AUTH_SESSION_DAYS=7

✅ 서비스 계정 키는 Firebase 콘솔 > 프로젝트 설정 > 서비스 계정에서 발급합니다.

Vercel에 배포 시 위 3개 값을 환경변수로 등록하세요.

키 생성을 하면 json 파일을 다운로드하게 됩니다. 그 파일을 열어서 환경변수를 채워줍니다.

1) Admin SDK 초기화

파이어베이스 어드민 설치

npm i firebase-admin

lib/firebase.admin.ts

import { cert, getApps, initializeApp, App } from 'firebase-admin/app';
import { getAuth } from 'firebase-admin/auth';
import { getFirestore } from 'firebase-admin/firestore';

let adminApp: App;

if (!getApps().length) {
  adminApp = initializeApp({
    credential: cert({
      projectId: process.env.FIREBASE_ADMIN_PROJECT_ID,
      clientEmail: process.env.FIREBASE_ADMIN_CLIENT_EMAIL,
      privateKey: process.env.FIREBASE_ADMIN_PRIVATE_KEY?.replace(/\\n/g, '\n'),
    }),
  });
} else {
  adminApp = getApps()[0]!;
}

export const adminAuth = getAuth(adminApp);
export const adminDb = getFirestore(adminApp);

역할

• 서버 런타임에서만 동작하는 Admin SDK 인스턴스(Auth/Firestore)를 싱글톤으로 초기화합니다.

동작 원리

• getApps().length로 중복 초기화 방지(개발 HMR/테스트 환경에서 중요).
• credential: cert({...})로 서비스 계정 자격 증명 주입.
• 내보낸 객체:
  • adminAuth → 세션쿠키 검증/생성 등 인증 서버 작업
  • adminDb → 서버 신뢰 컨텍스트에서 Firestore 읽기/쓰기

주의

• 클라이언트에서 import 금지. (App Router에서도 서버 파일에만 사용)

2) 세션 쿠키 API (로그인/로그아웃)

클라이언트에서 Firebase Auth로 로그인한 뒤, ID 토큰을 받아 서버에 전달 → 서버는 세션쿠키를 굽습니다.

이 쿠키는 Server Action에서 자동으로 전달되므로 별도 헤더 없이 인증이 가능합니다.

app/api/auth/session/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { adminAuth } from '@/lib/firebase.admin';

export async function POST(req: NextRequest) {
  // body: { idToken: string }
  const { idToken } = await req.json();
  if (!idToken)
    return NextResponse.json(
      { ok: false, message: 'NO_TOKEN' },
      { status: 400 }
    );

  const expiresIn =
    Number(process.env.AUTH_SESSION_DAYS ?? 7) * 24 * 60 * 60 * 1000;
  try {
    const sessionCookie = await adminAuth.createSessionCookie(idToken, {
      expiresIn,
    });

    const res = NextResponse.json({ ok: true });
    // httpOnly + secure 쿠키 설정
    res.cookies.set({
      name: '__session', // Firebase 호환 네이밍
      value: sessionCookie,
      httpOnly: true,
      secure: true,
      path: '/',
      maxAge: Math.floor(expiresIn / 1000),
      sameSite: 'lax',
    });
    return res;
  } catch (e) {
    return NextResponse.json(
      { ok: false, message: 'CREATE_SESSION_FAILED' },
      { status: 401 }
    );
  }
}

export async function DELETE() {
  // 쿠키 삭제
  const res = NextResponse.json({ ok: true });
  res.cookies.set({
    name: '__session',
    value: '',
    path: '/',
    maxAge: 0,
  });
  return res;
}

무엇을 하나요?

• 클라이언트(브라우저)에서 받은 ID 토큰을 서버로 보내면

  → 서버가 createSessionCookie로 HTTP-Only 세션쿠키를 굽습니다.

• 로그아웃은 해당 쿠키를 삭제합니다.

보안 속성

• httpOnly: true → JS로 쿠키 접근 불가(XSS 저항).
• secure: true → HTTPS에서만 전송(배포 환경 권장, 로컬 http에서는 생략 가능).
• sameSite: 'lax' → CSRF 기본 완화.

수명

• AUTH_SESSION_DAYS로 만료 시간 제어. 만료 후엔 다시 로그인해야 합니다.

오류 처리

• ID 토큰 누락/유효하지 않으면 400/401로 실패 반환 → 클라이언트는 재로그인 유도.

팁

보안 요구가 높다면 CSRF 토큰을 추가(예: 헤더 X-CSRF-Token)하고, 요청 헤더를 검증하세요.

클라이언트: 로그인 직후 세션 설정

app/login/page.tsx / app/signup/page.tsx에서 로그인 성공 후 아래 호출 추가:

import { getIdToken } from 'firebase/auth';

// 로그인/회원가입 성공 직후
const idToken = await getIdToken(auth.currentUser!, true);
await fetch('/api/auth/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ idToken }),
});

• 최종 적용 소스는 저장소 브랜치를 참고하세요.

흐름

1. Firebase Auth로 로그인 완료
2. getIdToken(currentUser, /*forceRefresh=*/true)로 최신 ID 토큰 발급
3. /api/auth/session에 POST → 서버가 세션쿠키 발급
4. 이후 Server Action/SSR에서 자동 인증됨(쿠키 기반)

로그아웃 시 세션 삭제

HeaderAuth.tsx의 로그아웃 버튼에서:

// 로그아웃 핸들러 (서버 세션 + 클라이언트 동시 로그아웃)
const handleLogout = async () => {
  try {
    // 1️⃣ 서버 세션 쿠키 삭제
    await fetch('/api/auth/session', { method: 'DELETE' });

    // 2️⃣ 클라이언트 Firebase Auth 로그아웃
    await signOut(auth);

    // 3️⃣ 새로고침 (상태 반영)
    window.location.href = '/';
  } catch (e) {
    console.error('로그아웃 실패:', e);
  }
};

<button
  onClick={handleLogout}
  style={{
    padding: '6px 10px',
    border: '1px solid #ddd',
    borderRadius: 8,
    background: 'white',
  }}
>
  로그아웃
</button>

이렇게 하면 클라이언트/서버 모두 동일한 인증 상태를 공유합니다.

로그아웃

1. /api/auth/session DELETE로 쿠키 삭제
2. auth.signOut()으로 클라이언트 세션 종료
3. 새로고침으로 UI 동기화

3) Server Actions: 안전한 CRUD 구현

(1) 액션 모듈 생성

app/actions/postActions.ts

'use server';

import { adminAuth, adminDb } from '@/lib/firebase.admin';
import { cookies } from 'next/headers';

async function requireUid() {
  const cookieStore = await cookies(); // Next 15: 반드시 await
  const session = cookieStore.get('__session')?.value;
  if (!session) throw new Error('UNAUTHORIZED');
  const decoded = await adminAuth.verifySessionCookie(session, true);
  return decoded.uid;
}

/** 글 생성 (단일 파라미터) */
export async function createPostAction(formData: FormData) {
  try {
    const uid = await requireUid();
    const title = (formData.get('title') as string)?.trim();
    const content = (formData.get('content') as string)?.trim() || '';
    const isPublic = formData.get('isPublic') === 'on';
    if (!title) throw new Error('제목을 입력하세요.');

    const docRef = await adminDb.collection('posts').add({
      uid,
      title,
      content,
      isPublic,
      thumbUrl: null,
      thumbPath: null,
      createdAt: new Date(),
      updatedAt: new Date(),
    });

    return { ok: true, id: docRef.id };
  } catch (e: any) {
    return { ok: false, message: e?.message ?? '글 생성 실패' };
  }
}

/** 글 수정 */
export async function updatePostAction(formData: FormData) {
  try {
    const uid = await requireUid();
    const id = (formData.get('id') as string)?.trim();
    const title = (formData.get('title') as string)?.trim();
    const content = (formData.get('content') as string)?.trim() || '';
    const isPublic = formData.get('isPublic') === 'on';
    if (!id) throw new Error('ID 누락');
    if (!title) throw new Error('제목을 입력하세요.');

    const ref = adminDb.collection('posts').doc(id);
    const snap = await ref.get();
    if (!snap.exists) throw new Error('NOT_FOUND');
    if (snap.get('uid') !== uid) throw new Error('FORBIDDEN');

    await ref.update({ title, content, isPublic, updatedAt: new Date() });
    return { ok: true };
  } catch (e: any) {
    return { ok: false, message: e?.message ?? '글 수정 실패' };
  }
}

/** 글 삭제 */
export async function deletePostAction(formData: FormData) {
  try {
    const uid = await requireUid();
    const id = (formData.get('id') as string)?.trim();
    if (!id) throw new Error('ID 누락');

    const ref = adminDb.collection('posts').doc(id);
    const snap = await ref.get();
    if (!snap.exists) throw new Error('NOT_FOUND');
    if (snap.get('uid') !== uid) throw new Error('FORBIDDEN');

    await ref.delete();
    return { ok: true };
  } catch (e: any) {
    return { ok: false, message: e?.message ?? '글 삭제 실패' };
  }
}

핵심 아이디어

• Server Actions에서만 Firestore를 조작하고, 항상 세션쿠키로 사용자 UID를 검증합니다.

requireUid() 동작

1. cookies()에서 __session 쿠키 추출
2. adminAuth.verifySessionCookie(session, true)로 유효성/만료 확인
3. 검증 성공 시 uid 반환, 실패 시 에러(UNAUTHORIZED)

각 액션의 공통 보안 패턴

• 서버에서 FormData 재검증(필수값/길이/형식) → 신뢰할 수 없는 입력 방어
• 문서 수정/삭제 시:
  • 대상 문서 조회 → 존재 여부 확인
  • 문서의 uid와 현재 uid가 일치하는지 검사(소유자만 허용)

반환값 패턴

• 항상 { ok: boolean, message?: string, id?: string } 형태로 에러/성공 구분
• 클라이언트는 해당 값을 받아 UI 피드백/리다이렉트 처리

팁

Next 15 기준 cookies()는 await 필요합니다(사용하신 코드처럼). 버전별 차이를 인지하세요.

4) Form에서 Server Actions 호출하기

(1) 새 글 작성 페이지 (서버액션 버전)

app/posts/new/page.tsx

import { createPostAction } from '@/app/actions/postActions';
import { redirect } from 'next/navigation';

export const dynamic = 'force-dynamic';

export default function NewPostPage() {
  // ✅ 단일 파라미터(폼데이터)만 받는 서버 함수
  async function handleAction(formData: FormData) {
    'use server';
    const res = await createPostAction(formData);
    if (!res.ok) {
      console.error(res.message);
      return;
    }
    redirect(`/posts/${res.id}`);
  }

  return (
    <main style={{ maxWidth: 720, margin: '40px auto', padding: 16 }}>
      <h1>새 글 작성 (Server Action)</h1>
      <form action={handleAction} style={{ display: 'grid', gap: 12 }}>
        <input
          name='title'
          placeholder='제목'
          style={{ padding: 10, border: '1px solid #ddd', borderRadius: 8 }}
        />
        <textarea
          name='content'
          placeholder='내용(선택)'
          rows={8}
          style={{ padding: 10, border: '1px solid #ddd', borderRadius: 8 }}
        />
        <label style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
          <input type='checkbox' name='isPublic' defaultChecked />
          공개글로 등록
        </label>
        <button type='submit' style={{ padding: '10px 12px', borderRadius: 8 }}>
          등록
        </button>
      </form>
    </main>
  );
}

중요: 이 페이지로 오기 전에 /api/auth/session이 설정되어 있어야 합니다.

(로그인 후 세션 쿠키를 세팅하는 과정)

흐름

• <form action={handleAction}>에 서버 인라인 함수를 연결
• 서버에서 createPostAction(formData) 호출 → 성공 시 redirect('/posts/{id}')

왜 좋아요?

• 네트워크/보안 단순화: 별도 fetch/헤더 없이 쿠키로 인증 전파
• 코드 분기 최소화: 폼 제출 = 서버 실행 = 리다이렉트

(2) 상세 페이지에서 수정/삭제 (서버액션 버전)

app/posts/[id]/page.tsx (핵심만 발췌)

import { adminDb } from '@/lib/firebase.admin';
import { updatePostAction, deletePostAction } from '@/app/actions/postActions';
import { redirect } from 'next/navigation';

export const dynamic = 'force-dynamic';

export default async function PostDetail({
  params,
}: {
  params: { id: string };
}) {
  const snap = await adminDb.collection('posts').doc(params.id).get();
  if (!snap.exists) return <main>존재하지 않는 글입니다.</main>;
  const post = { id: snap.id, ...(snap.data() as any) };

  async function onUpdate(formData: FormData) {
    'use server';
    formData.set('id', post.id);
    const res = await updatePostAction(formData);
    if (!res.ok) {
      console.error(res.message);
      return;
    }
    // 필요하면 revalidatePath('/posts') 등 추가
  }

  async function onDelete(formData: FormData) {
    'use server';
    formData.set('id', post.id);
    const res = await deletePostAction(formData);
    if (!res.ok) {
      console.error(res.message);
      return;
    }
    redirect('/posts');
  }

  return (
    <main style={{ maxWidth: 720, margin: '40px auto', padding: 16 }}>
      <h1>{post.title}</h1>
      {post.content && <p style={{ whiteSpace: 'pre-wrap' }}>{post.content}</p>}

      <form
        action={onUpdate}
        style={{ display: 'grid', gap: 8, marginTop: 24 }}
      >
        <input name='title' defaultValue={post.title} />
        <textarea name='content' defaultValue={post.content} rows={6} />
        <label style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
          <input
            type='checkbox'
            name='isPublic'
            defaultChecked={post.isPublic}
          />
          공개글
        </label>
        <button type='submit'>수정</button>
      </form>

      <form action={onDelete} style={{ marginTop: 12 }}>
        <button
          type='submit'
          style={{ border: '1px solid #f33', color: '#f33' }}
        >
          삭제
        </button>
      </form>
    </main>
  );
}

흐름

• 서버 컴포넌트에서 문서 스냅샷 adminDb로 SSR 시점에 얻음
• 수정/삭제 <form action={onUpdate|onDelete}>로 각각 서버액션 호출
• 수정은 성공 후 **재검증(revalidatePath)**이나 낙관적 업데이트 패턴을 붙이면 UX 업그레이드
• 삭제는 성공 시 redirect('/posts')

팁

목록 캐시를 쓰는 경우, 수정/삭제 후 revalidatePath('/posts')를 호출해 SSR 캐시 갱신을 보장하세요.

5) 폼 유효성 & 에러 표시(간단 패턴)

Server Action은 객체를 반환하여 클라이언트에서 에러를 표시할 수 있습니다.

위 예시처럼 { error: string }을 리턴하고, 클라이언트에서 조건부로 보여주면 됩니다.

좀 더 정교하게 하려면 필드별 에러를 { fieldErrors: { title?: string, content?: string } }로 내려 주세요.

생산환경에선 zod로 스키마 검증을 도입하는 것을 권장합니다.

6) 체크리스트

• 로그인/회원가입 성공 직후 /api/auth/session에 POST 호출로 세션 쿠키 설정
• HeaderAuth 로그아웃 시 /api/auth/session DELETE + auth.signOut()
• createPostAction / updatePostAction / deletePostAction에서 UID 검증 성공
• 클라이언트에서 form action으로 Server Action 호출 시 정상 동작

실습저장소

GitHub - heroyooi/nextjs-firebase at ch1_5