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

0) 배포 전 필수 점검

• firebase.admin.ts 사용 중 ⇒ 환경변수 3종(Project ID / Client Email / Private Key) 준비

  왜 Admin 환경변수 3종이 필요하나요?

  • firebase-admin은 서버 전용 자격증명으로 동작합니다.
    • projectId, clientEmail, privateKey가 정확해야 verifySessionCookie, Firestore/Storage 서버 액세스가 가능합니다.

• 로그인 후 세션쿠키 API(/api/auth/session)가 동작하는지 로컬에서 확인

  세션쿠키 API 사전 점검 포인트

  • 로컬에서 로그인 성공 → getIdToken() → /api/auth/session에 POST 후, 브라우저 쿠키에 __session이 생성되는지 확인하세요.

  • 개발 환경(http)에서는 secure: true 쿠키가 저장되지 않을 수 있습니다.

    → 보통 secure: process.env.NODE_ENV === 'production'으로 분기합니다.

• next/image를 쓸 예정이면 Storage 도메인 허용 설정 필요

  next/image 원격 도메인 허용 이유

  • next/image는 도메인 화이트리스트 방식입니다.

    • Firebase Storage Web URL(firebasestorage.googleapis.com)

    • Admin SDK 서명 URL(storage.googleapis.com)

    • 구글 사용자 이미지(.googleusercontent.com)

      를 허용하지 않으면 이미지가 차단됩니다.

1) Vercel 배포

(0) 프로젝트 세팅

진행중인 저장소 Vercel에 프로젝트 등록

(1) 환경변수 등록

Vercel → Project → Settings → Environment Variables 에 아래 키 추가(Production / Preview / Development 모두):

# Admin SDK (서버 전용, NEXT_PUBLIC 금지)
FIREBASE_ADMIN_PROJECT_ID=your-project-id
FIREBASE_ADMIN_CLIENT_EMAIL=firebase-adminsdk-xxxx@your-project-id.iam.gserviceaccount.com
FIREBASE_ADMIN_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\nABC...XYZ\n-----END PRIVATE KEY-----\n

# 세션 수명(일)
AUTH_SESSION_DAYS=7

# 클라이언트 SDK
NEXT_PUBLIC_FIREBASE_API_KEY=...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=...
NEXT_PUBLIC_FIREBASE_PROJECT_ID=...
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=...
NEXT_PUBLIC_FIREBASE_APP_ID=...
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=...

Private Key 줄바꿈: \n 그대로 넣어도 되고, Vercel “Raw” 토글로 실제 개행을 넣어도 됩니다.

코드는 replace(/\\n/g, '\n')로 처리 중이라 두 방식 모두 호환됩니다.

Vercel 에서는 저장소에서 확인되는 프레임워크들을 자동으로 인식합니다. Framework Preset은 Next.js로 자동으로 잡히며 환경 변수들만 세팅해서 배포해줍니다.

배포시 에러가 나면 소스를 고쳐주어야 합니다. 이건 Vercel 빌드 중 TypeScript + ESLint 규칙(no-explicit-any) 때문에 빌드가 실패한 케이스입니다. 본 강좌는 Next.js 및 Firebase를 배우는 것이 목적이므로 ESLint 에러는 비활성화하도록 하겠습니다.

Next.js 설정(next.config.ts)에 아래 추가:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  eslint: {
    ignoreDuringBuilds: true, // 🚀 ESLint 무시하고 빌드 통과
  },
};

export default nextConfig;

ESLint를 비활성화하고 배포를 시도하면 다음과 같은 에러로 바뀝니다.

이 부분은 Promise로 전달되는 타입이 기본값이라서 지금처럼 { params: { id: string } }로 선언하면 에러가 납니다. 이 부분만 수정해서 다시 배포를 시도합니다. params를 Promise로 받고 await 합니다.

app/posts/[id]/page.tsx

// 생략...

export default async function PostDetail({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;

  const snap = await adminDb.collection('posts').doc(id).get();
  
	// 생략...
}

위 코드와 같이 변경하고 메인 브랜치에 Push 하면 자동으로 Vercel에 배포가 이루어지며 배포 성공시 다음과 같은 화면을 확인하실 수 있습니다.

nextjs-firebase-flame.vercel.app

위 배포 URL은 자유롭게 변경할 수 있습니다. 이 부분은 추후에 다루도록 하겠습니다.

2) 이미지 최적화 (next/image + Storage 호환)

(1) app/posts/new/page.tsx Server Action 기반으로 이미지 업로드 구현

환경변수를 추가하세요(로컬 .env.local + Vercel 프로젝트 설정 둘 다):

FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com

Firebase 콘솔 → 프로젝트 설정 → 일반 → 스토리지 버킷 이름 확인

보통 프로젝트ID.appspot.com 형태입니다.

lib\firebase.admin.ts

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

const STORAGE_BUCKET =
  process.env.FIREBASE_STORAGE_BUCKET ?? // 서버용 권장
  process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET ?? // 임시 fallback
  '';

if (!STORAGE_BUCKET || STORAGE_BUCKET.startsWith('gs://')) {
  // 서버 콘솔에서 바로 보이게 경고
  console.warn('[firebase.admin] Invalid STORAGE_BUCKET:', STORAGE_BUCKET);
}

const adminApp = getApps().length
  ? getApps()[0]!
  : 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'
        )!,
      }),
      // ✅ 기본 버킷을 반드시 지정
      storageBucket: STORAGE_BUCKET || undefined,
    });

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

app\actions\postActions.ts

'use server';

import { adminAuth, adminDb, adminStorage } 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;
}

const BUCKET =
  process.env.FIREBASE_STORAGE_BUCKET ??
  process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET!;

/** 글 생성 (단일 파라미터) */
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';
    const file = formData.get('file') as File | null; // ← input name="file"

    if (!title) throw new Error('제목을 입력하세요.');

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

    let thumbUrl: string | null = null;
    let thumbPath: string | null = null;

    if (file && file.size > 0) {
      const fileName = `${Date.now()}-${file.name}`;
      thumbPath = `users/${uid}/posts/${ref.id}/${fileName}`;

      // File → Buffer
      const buffer = Buffer.from(await file.arrayBuffer());

      // 업로드
      const bucket = adminStorage.bucket(BUCKET); // 기본 버킷
      const gcsFile = bucket.file(thumbPath);
      await gcsFile.save(buffer, {
        contentType: file.type || 'application/octet-stream',
        resumable: false,
        public: false, // 기본 비공개
        metadata: { cacheControl: 'public, max-age=31536000, immutable' },
      });

      // 사인드 URL 생성(읽기용) — 필요시 만료 연장
      const [signedUrl] = await gcsFile.getSignedUrl({
        action: 'read',
        expires: Date.now() + 1000 * 60 * 60 * 24 * 365, // 1년
      });
      thumbUrl = signedUrl;

      await ref.update({ thumbUrl, thumbPath, updatedAt: new Date() });
    }

    return { ok: true, id: ref.id };
  } catch (e: any) {
    console.error(e);
    return { ok: false, message: e?.message ?? 'CREATE_FAILED' };
  }
}

// 생략...

app/posts/new/page.tsx

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

export const dynamic = 'force-dynamic';
export const runtime = 'nodejs'; // ✅ 추가

export default function NewPostPage() {
  // 생략...

  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>
        <input type='file' name='file' accept='image/*' />{/* ✅ 파일 업로드 필드 */}
        <button type='submit' style={{ padding: '10px 12px', borderRadius: 8 }}>
          등록
        </button>
      </form>
    </main>
  );
}

src\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: Promise<{ id: string }>;
}) {
  const { id } = await params;

  // 생략...

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

      {/* 생략 */}
    </main>
  );
}

(1) next.config.ts 도메인 허용

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  eslint: { ignoreDuringBuilds: true },
  images: {
    remotePatterns: [
      // Firebase Storage (Web SDK 일반 URL)
			{ protocol: 'https', hostname: 'firebasestorage.googleapis.com' },
      // Googleusercontent
      { protocol: 'https', hostname: '**.googleusercontent.com' },
      // Admin SDK Signed URL
      { protocol: 'https', hostname: 'storage.googleapis.com' },
    ],
  },
};

export default nextConfig;

(2) 상세/목록 이미지 교체

import Image from 'next/image';

// 예시
{post.thumbUrl && (
  <Image src={post.thumbUrl}
    alt=""
    width={720}
    height={420}
    style={{ width: '100%', height: 'auto', borderRadius: 12 }}
    priority
  />
)}

• 상세한 내용은 해당 강좌 저장소 브랜치에서 확인하세요.

3) SEO: metadata / OG / robots / sitemap

(1) 전역 메타데이터 (app/layout.tsx)

export const metadata = {
  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000'),
  title: {
    default: 'Next.js + Firebase 실전 앱',
    template: '%s | Next.js + Firebase',
  },
  description: 'Next.js(App Router)와 Firebase로 로그인/CRUD/이미지 업로드까지 구현하는 실전 프로젝트',
  openGraph: {
    type: 'website',
    title: 'Next.js + Firebase 실전 앱',
    description: '로그인/CRUD/Storage',
    url: '/',
    images: [{ url: '/og.png', width: 1200, height: 630 }],
  },
};

배포 환경에서 NEXT_PUBLIC_SITE_URL(예: https://nextjs-firebase.vercel.app)을 넣어두면 정규화된 URL이 생성됩니다. 일단 실습 자료는 NEXT_PUBLIC_SITE_URL 값으로 Vercel에서 제공해준 https://nextjs-firebase-flame.vercel.app를 넣도록 하겠습니다.

(2) 페이지 개별 메타 (app/posts/[id]/page.tsx)

SSR에서 문서 타이틀/요약을 반영하려면:

export async function generateMetadata({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const snap = await adminDb.collection('posts').doc(id).get();
  if (!snap.exists) return { title: '게시글 없음' };
  const data = snap.data() as any;
  return {
    title: data.title,
    description: (data.content ?? '').slice(0, 100),
  };
}

(3) robots & sitemap

app/robots.ts

import type { MetadataRoute } from 'next';

export default function robots(): MetadataRoute.Robots {
  const base = process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000';
  return {
    rules: [{ userAgent: '*', allow: '/' }],
    sitemap: `${base}/sitemap.xml`,
  };
}

app/sitemap.ts

import type { MetadataRoute } from 'next';
import { adminDb } from '@/lib/firebase.admin';

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const base = process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000';

  // 공개 글만
  const snap = await adminDb.collection('posts').where('isPublic', '==', true).get();

  const posts = snap.docs.map(d => ({
    url: `${base}/posts/${d.id}`,
    lastModified: (d.get('updatedAt')?.toDate?.() as Date) || new Date(),
    changeFrequency: 'weekly' as const,
    priority: 0.7,
  }));

  return [
    { url: base, lastModified: new Date() },
    { url: `${base}/posts`, lastModified: new Date() },
    ...posts,
  ];
}

4) 렌더링/캐시 전략 (App Router)

빠르게 정리

• 자주 변하는 데이터: 페이지 상단에

  export const dynamic = 'force-dynamic'; // 서버가 매 요청 새로 그림
  

• 정적 + 주기적 갱신(ISR):

  export const revalidate = 60; // 초 단위
  

• 서버에서 데이터 갱신 후 리스트 갱신:

  액션에서 revalidatePath('/posts') 혹은 revalidateTag('posts') 사용.

예) 글 생성 후 목록 갱신:

import { revalidatePath } from 'next/cache';

export async function createPostAction(formData: FormData) {
  // ...생성 로직
  revalidatePath('/posts'); // 목록 페이지 캐시 무효화
  return { ok: true, id: docRef.id };
}

클라이언트 fetch엔 next: { revalidate: n } 또는 cache: 'no-store'를 지정할 수 있지만, Firestore SDK를 직접 쓰는 경우엔 해당 옵션이 적용되지 않습니다. 이럴 땐 서버에서 직접 새로 그리거나(revalidate/dynamic), 클라이언트 onSnapshot으로 실시간 유지가 가장 간단합니다.

5) 폰트/이미지/번들 최적화

(1) 웹폰트 (next/font)

app/layout.tsx

import { Noto_Sans_KR } from 'next/font/google';
const noto = Noto_Sans_KR({ subsets: ['latin'], weight: ['400','500','700'], display: 'swap' });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body className={noto.className}>{children}</body>
    </html>
  );
}

(2) 번들 크기 점검(선택)

• 해당 과정은 생략해도 괜찮습니다.

npm i -D @next/bundle-analyzer

next.config.ts

import type { NextConfig } from 'next';
import bundleAnalyzer from '@next/bundle-analyzer';

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
});

const nextConfig: NextConfig = {
  eslint: { ignoreDuringBuilds: true },
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'firebasestorage.googleapis.com' },
      { protocol: 'https', hostname: '**.googleusercontent.com' },
      { protocol: 'https', hostname: 'storage.googleapis.com' },
    ],
  },
};

export default withBundleAnalyzer(nextConfig);

.env.local

ANALYZE=true

터미널 실행:

npm run build

ANALYZE=true 설정하고 로컬 서버에서 빌드를 실행하면 다음과 같은 브라우저 창이 뜨는 것을 확인할 수 있습니다.

1️⃣ nodejs.html - 서버 사이드(Server Components + Server Actions 번들)

이건 Next.js 서버 런타임에서 동작하는 코드 (SSR, Server Action, Metadata, Firebase Admin SDK 등) 를 분석한 결과입니다.

🔍 주요 관찰 포인트

2️⃣ client.html - 클라이언트 번들(Client Components)

이건 브라우저로 전송되는 코드 분석 결과로, 사용자가 실제 다운로드받는 JS 리소스를 보여줍니다.

🔍 주요 관찰 포인트

👉 요약

• @firebase/auth, @firebase/firestore 가 합쳐서 약 100~150KB 정도 차지 (Firebase SDK 특성상 불가피)
• Next.js 라우터 및 React Core 가 약 300KB
• 나머지는 페이지별 entry module 분리로 잘 나뉘어 있음

6) 배포 후 헬스체크 페이지(선택)

서버에서 세션 UID가 잘 읽히는지 확인:

app/me/page.tsx

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

export default async function MePage() {
  const cookieStore = await cookies();
  const session = cookieStore.get('__session')?.value;

  if (!session)
    return <main style={{ padding: 16 }}>로그인 세션이 없습니다.</main>;

  try {
    const decoded = await adminAuth.verifySessionCookie(session, true);
    return <main style={{ padding: 16 }}>현재 UID: {decoded.uid}</main>;
  } catch {
    return <main style={{ padding: 16 }}>세션이 유효하지 않습니다.</main>;
  }
}

체크리스트 (한 번에 점검)

• Vercel 환경변수 3종(Admin) + 클라 공개 키들 반영
• /api/auth/session에서 secure = prod 전용 적용
• next.config.js에 Storage 원격 이미지 도메인 허용
• metadata/robots/sitemap 설정 완료
• 목록·상세 페이지 캐시 정책 결정(dynamic or revalidate)
• 배포 후 /login → /posts/new → /posts/[id] 정상
• /me 페이지에서 UID 확인 OK

실습저장소

GitHub - heroyooi/nextjs-firebase at ch1_6

실습 배포 URL

Next.js + Firebase 실전 앱