admin-starter-kit 만들기 (1)

Next.js 16 + Supabase로 어드민 대시보드 만들기 (1)

– 초기 세팅과 에러 디버깅 로그

0. 프로젝트 스택 정리

Framework: Next.js 16 (App Router, app 디렉터리 구조)
UI: Tailwind CSS, Radix UI 기반 컴포넌트
Auth / Backend: Supabase (@supabase/ssr, @supabase/supabase-js)
언어: TypeScript

이번 글에서는 초기 개발 단계에서 만난 몇 가지 에러를 정리하고, 그것을 어떻게 이해하고 해결(또는 해결 방향을 설계)했는지 기록한다.

1. 랜딩 페이지에서 `next/router` 에러

랜딩 페이지 파일은 src/app/(marketing)/page.tsx에 두었다.
버튼 클릭으로 로그인 페이지(/login)로 보내기 위해 아래와 같이 작성했었다.

tsx

// src/app/(marketing)/page.tsx
import { Button } from '@/components/ui/button';
import { Router, useRouter } from 'next/router';

export default function MarketingPage() {
  const router = useRouter();

  return (
    <div className="flex flex-col items-center justify-center h-full gap-4">
      <h1 className="text-3xl font-bold">여기는 랜딩 페이지입니다</h1>
      <Button onClick={() => router.push('/login')}>로그인 하러가기</Button>
    </div>
  );
}

Next.js가 알려준 에러는 다음과 같다.

You have a Server Component that imports next/router. Use next/navigation instead.

1-1. 왜 이런 에러가 나는가?

src/app/(marketing)/page.tsx는 App Router 환경의 Server Component다.
App Router에서는:
- next/router는 Pages Router 전용 API라서 사용 불가
- 대신 **next/navigation**의 useRouter, redirect, useSearchParams 등을 사용해야 한다.
- 그리고 useRouter 훅은 클라이언트 컴포넌트에서만 사용할 수 있다.

즉, 이 페이지는 “서버 컴포넌트 + next/router + 훅”이라는 조합 때문에 에러가 난 것이다.

1-2. 해결 방향 정리

이 문제를 해결하는 방법은 크게 두 가지 방향이 있다.

페이지를 클라이언트 컴포넌트로 전환
- 파일 상단에 "use client";
- next/router → next/navigation으로 변경
- useRouter를 그대로 사용하면서 버튼 클릭 시 router.push('/login')
Server Component 유지 + Link 컴포넌트 사용
- useRouter 대신 next/link의 Link로 네비게이션 처리
- Supabase나 React 훅이 필요 없고, 단순 이동만 필요하다면 이 방법이 훨씬 간단

이번 글에서는 에러의 원인과 해결 전략까지만 정리했고, 실제 구현 선택과 리팩터링은 이후 단계에서 진행할 예정이다.

2. Supabase 서버 클라이언트에서 `cookies()` 타입 에러

Supabase 서버용 클라이언트는 src/lib/supabase/server.ts에 만들었다.
처음 버전은 대략 이런 형태였다.

// src/lib/supabase/server.ts
import { createServerClient, type CookieOptions } from '@supabase/ssr';
import { cookies } from 'next/headers';

export function createClient() {
  const cookieStore = cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        get(name: string) {
          return cookieStore.get(name)?.value;
        },
        set(name: string, value: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value, ...options });
          } catch (error) {
            // Server Component에서는 쿠키 조작 불가 에러 무시
          }
        },
        remove(name: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value: '', ...options });
          } catch (error) {
            // Server Component에서는 쿠키 조작 불가 에러 무시
          }
        },
      },
    }
  );
}

TypeScript 린터가 잡아준 에러는 다음과 같았다.

Property 'get' does not exist on type 'Promise<ReadonlyRequestCookies>'.
Property 'set' does not exist on type 'Promise<ReadonlyRequestCookies>'.

2-1. 에러 원인

프로젝트의 package.json을 보면:

next: 16.1.6
@supabase/ssr: ^0.8.0

이 버전 조합에서는 next/headers의 cookies()가 동기 객체가 아니라 Promise<ReadonlyRequestCookies>로 타입 정의되어 있다.
그런데 기존 코드에서는 const cookieStore = cookies();라고 동기처럼 사용하고 있었기 때문에:

cookieStore 타입이 Promise<ReadonlyRequestCookies>
따라서 cookieStore.get, cookieStore.set 등은 존재하지 않는다는 에러가 발생

2-2. 해결: `createClient`를 async로 변경

이 문제를 해결하기 위해 서버용 클라이언트 팩토리를 비동기 함수로 변경했다.

// src/lib/supabase/server.ts
import { createServerClient, type CookieOptions } from '@supabase/ssr';
import { cookies } from 'next/headers';

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        get(name: string) {
          return cookieStore.get(name)?.value;
        },
        set(name: string, value: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value, ...options });
          } catch (error) {
            // Server Component에서는 쿠키 조작 불가 에러 무시
          }
        },
        remove(name: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value: '', ...options });
          } catch (error) {
            // Server Component에서는 쿠키 조작 불가 에러 무시
          }
        },
      },
    }
  );
}

핵심 변화는 두 줄이다.

export function createClient() → export async function createClient()
const cookieStore = cookies(); → const cookieStore = await cookies();

이렇게 한 뒤 다시 린트를 돌리면, server.ts의 타입 에러는 모두 사라진다.

3. Dashboard 레이아웃에서 Supabase 클라이언트 사용 에러

Supabase 서버 클라이언트를 만든 다음, 대시보드 레이아웃에서 로그인된 사용자 정보를 서버에서 직접 가져오기 위해 아래와 같이 작성했었다.

tsx

// src/app/dashboard/layout.tsx
import { Header } from '@/components/layout/header';
import { Sidebar } from '@/components/layout/sidebar';
import { createClient } from '@/lib/supabase/server';
import { redirect } from 'next/navigation';

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // 1. 서버에서 로그인 정보 가져오기
  const supabase = createClient();
  const {
    data: { user },
  } = await supabase.auth.getUser();

  // 2. 혹시나 미들웨어가 뚫렸을 경우를 대비한 이중 체크
  if (!user) {
    redirect('/login');
  }

  return (
    // ...
  );
}

하지만 createClient()를 앞에서 async 함수로 바꿨기 때문에, 여기에서도 새로운 타입 에러가 발생했다.

Property 'auth' does not exist on type 'Promise<SupabaseClient<...>>'.

즉, supabase가 SupabaseClient가 아니라 Promise<SupabaseClient> 타입이 되어버린 것이다.

3-1. 해결: `await createClient()`로 호출

레이아웃 함수가 이미 async이기 때문에, 여기서는 단순히 await만 붙여주면 된다.

tsx

// src/app/dashboard/layout.tsx
export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // 1. 서버에서 로그인 정보 가져오기
  const supabase = await createClient();
  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user) {
    redirect('/login');
  }

  return (
    <div className="h-full relative">
      <div className="hidden h-full md:flex md:w-72 md:flex-col md:fixed md:inset-y-0 z-[80] bg-gray-900">
        <Sidebar />
      </div>
      <main className="md:pl-72 h-full">
        <div className="h-[60px] md:h-[80px] fixed inset-y-0 w-full z-50 md:pl-72">
          <Header userEmail={user.email} />
        </div>
        <div className="flex flex-col h-full pt-16 md:pt-20">
          <div className="p-8 h-full bg-slate-50/50">{children}</div>
        </div>
      </main>
    </div>
  );
}

이렇게 수정한 뒤에는:

DashboardLayout에서의 Supabase 관련 타입 에러가 모두 해결
남은 것은 Tailwind 관련 린트 경고(예: z-[80] 대신 z-80 권장) 정도라서, 실제 빌드/실행에는 문제가 없다.

4. 여기까지 정리

지금까지 진행한 내용은 다음과 같다.

랜딩 페이지((marketing)/page.tsx)
- App Router에서 next/router를 사용해 발생한 에러를 분석
- next/navigation + Client Component vs Link 기반 Server Component라는 두 가지 해결 전략을 정리
Supabase 서버 클라이언트(lib/supabase/server.ts)
- cookies()가 Promise로 타입 지정된 Next 16 환경에서의 타입 에러를 확인
- createClient를 async 함수로 변경하고 await cookies()로 수정하여 해결
대시보드 레이아웃(app/dashboard/layout.tsx)
- createClient가 async로 바뀌면서 생긴 Promise 타입 문제를 await createClient()로 해결
- 로그인한 사용자가 없으면 redirect('/login')로 보호하는 서버 사이드 가드 구현

admin-starter-kit 만들기 (1)

Next.js 16 + Supabase로 어드민 대시보드 만들기 (1)

– 초기 세팅과 에러 디버깅 로그

0. 프로젝트 스택 정리

1. 랜딩 페이지에서 `next/router` 에러

1-1. 왜 이런 에러가 나는가?

1-2. 해결 방향 정리

2. Supabase 서버 클라이언트에서 `cookies()` 타입 에러

2-1. 에러 원인

2-2. 해결: `createClient`를 async로 변경

3. Dashboard 레이아웃에서 Supabase 클라이언트 사용 에러

3-1. 해결: `await createClient()`로 호출

4. 여기까지 정리

함께 읽으면 좋은 다른 개발일지

댓글

Next.js 16 + Supabase로 어드민 대시보드 만들기 (1)

– 초기 세팅과 에러 디버깅 로그

0. 프로젝트 스택 정리

1. 랜딩 페이지에서 next/router 에러

1-1. 왜 이런 에러가 나는가?

1-2. 해결 방향 정리

2. Supabase 서버 클라이언트에서 cookies() 타입 에러

2-1. 에러 원인

2-2. 해결: createClient를 async로 변경

3. Dashboard 레이아웃에서 Supabase 클라이언트 사용 에러

3-1. 해결: await createClient()로 호출

4. 여기까지 정리

함께 읽으면 좋은 다른 개발일지

댓글

1. 랜딩 페이지에서 `next/router` 에러

2. Supabase 서버 클라이언트에서 `cookies()` 타입 에러

2-2. 해결: `createClient`를 async로 변경

3-1. 해결: `await createClient()`로 호출