[Next.js + TS 실전] 9. FAQ · 시리즈 총정리

입문 8편 + 실전 8편으로 작은 메모 앱을 끝까지 밀어 봤습니다.
마지막은 한눈에 지도, 자주 막히는 FAQ, 다음에 뭐 할지입니다.

이 글에서 하는 일

시리즈 전체 목차 정리
지금 앱이 할 수 있는 것 체크
실제로 자주 터지는 에러 Q&A
학습 로드맵 짧게

새 기능 추가는 없습니다.
복습·북마크용 글입니다.

시리즈 지도

입문 `[Next.js + TS]`

편	주제
1	왜 Next.js + TypeScript인가
2	프로젝트 만들고 폴더 구조
3	컴포넌트 타입 (Memo, props)
4	라우팅과 레이아웃
5	Server vs Client Component
6	데이터 가져오기 (async, loading/error)
7	폼과 Server Action
8	정리 + 다음 로드맵

실전 `[Next.js + TS 실전]`

편	주제
1	메모 수정과 삭제
2	Prisma + SQLite
3	Vercel 배포 (SQLite 한계)
4	폼 검증 (zod + useActionState)
5	로그인 (Clerk) + userId
6	Neon Postgres
7	삭제 확인 UI
8	목록 검색과 정렬
9	FAQ · 총정리 ← 지금

우리가 만든 것

메모 앱 기준으로 대략 이 정도입니다.

/                 소개
/memos            목록 (+ 검색·정렬)
/memos/new        작성 (+ zod 검증)
/memos/[id]       상세 (+ 삭제 확인)
/memos/[id]/edit  수정

기술 축:

App Router + TypeScript
Server Component 기본, 필요한 곳만 Client
Prisma (SQLite → Neon 가능)
Server Action CRUD
Clerk 로그인 + 내 메모만
Vercel 배포 이슈 이해

스스로 점검 체크리스트

기본

app/page.tsx = /, app/memos/page.tsx = /memos
layout.tsx와 page.tsx 차이를 설명할 수 있다
props / Memo 타입을 붙일 수 있다

서버·클라이언트

기본은 Server Component다
hooks / onClick이 있으면 Client로 분리한다
페이지 전체가 아니라 버튼·폼만 Client로 뺄 수 있다

데이터·폼

목록은 서버에서 await로 가져온다
쓰기는 Server Action + revalidatePath
zod로 검증하고 실패 시 상태 객체를 반환한다

인증·배포

미들웨어는 세션 연결, 보호는 auth.protect() / userId 쿼리
SQLite 파일은 Vercel과 안 맞는 이유를 안다
비밀 값은 .env / Vercel env에만 둔다

하나라도 막히면 해당 편만 다시 보면 됩니다.

FAQ (실제로 자주 막히는 것)

Q1. `/memos`가 404예요

원인 후보: 목록 파일에 상세 코드를 붙여 넣음.

파일	URL
`app/memos/page.tsx`	`/memos` 목록
`app/memos/[id]/page.tsx`	`/memos/1` 상세

상세(수정/삭제) 코드는 [id]/page.tsx 에 넣어야 합니다.
목록에 notFound()가 있으면 /memos도 404가 납니다.

Q2. `package.json`이 깨져서 npm이 안 돼요

시드 설정을 별도 객체로 하나 더 붙이면 JSON이 깨집니다.

잘못된 예:

  "devDependencies": { ... },
  {
    "prisma": { "seed": "..." }
  }
}

올바른 예 — 맨 바깥 키:

  "devDependencies": { ... },
  "prisma": {
    "seed": "npx tsx prisma/seed.ts"
  }
}

Q3. `userId` 마이그레이션이 실패해요

에러 예:

Added the required column userId without a default value. There are N rows...

이미 있는 행에 userId를 뭘로 채울지 몰라서입니다.

로컬 연습이면:

npx prisma migrate reset

데이터 삭제 후 스키마를 다시 맞춥니다.
그다음 시드에 userId도 넣어야 합니다. ("seed-user" 등)

Q4. 시드 메모가 로그인 목록에 안 보여요

정상일 수 있습니다.
시드 userId와 Clerk 로그인 userId가 다르기 때문입니다.

로그인 후 새로 작성한 메모로 확인하세요.

Q5. `createRouteMatcher`가 deprecated래요

최신 Clerk는 미들웨어에서 경로로 막지 말고,
페이지/레이아웃에서 auth.protect() 하라고 바뀌었습니다.

proxy.ts (또는 middleware.ts) → clerkMiddleware()만
app/memos/layout.tsx → await auth.protect()

Q6. `SignedOut` / `SignedIn`을 찾을 수 없어요

Clerk Core 3 / 최신 SDK에서는 Show 로 통합되었습니다.

<Show when="signed-out">...</Show>
<Show when="signed-in">...</Show>

ClerkProvider는 <html>을 감싸지 말고 <body> 안에 두는 형태를 권장합니다.

Q7. `parsed.error.flatten()`이 deprecated래요

Zod 4:

// 예전
parsed.error.flatten().fieldErrors

// 지금
z.flattenError(parsed.error).fieldErrors

Q8. `revalidatePath`는 뭐예요?

“이 경로 화면을 다시 준비해라”는 신호입니다.
메모를 추가/수정/삭제한 뒤 목록·상세가 옛 데이터로 남지 않게 합니다.

redirect = 이동, revalidatePath = 그 경로 캐시/데이터 갱신.

Q9. Prisma를 루트에 설치하고 memo-app에서 import했어요

앱은 memo-app 기준입니다.

패키지: memo-app에서 npm install
스키마: memo-app/prisma
명령: cd memo-app 후 npx prisma ...

루트(toyproject)와 섞이면 PrismaClient export 에러가 납니다.

Q10. Vercel에 올렸더니 데이터가 안 남아요 / DB 에러

SQLite file:./dev.db는 서버리스와 안 맞습니다.
Neon 등 외부 Postgres + Vercel DATABASE_URL이 필요합니다. (실전 3·6편)

Q11. 티스토리에 붙였더니 코드 블록이 안 먹어요

마크다운 모드인지 확인
```prisma 같은 생소한 언어 태그보다 ts / bash 또는 태그 없는 fence
JSX가 많은 블록은 미리보기에서 한 번 확인

채팅에서 복사할 때 코드펜스가 중간에 끊기면, .md 파일을 통째로 복사하는 편이 안전합니다.

한 줄로 다시 보는 핵심

주제	한 줄
Next	React로 앱 만드는 프레임워크 (폴더 = URL)
TS	데이터·props 계약
Server / Client	기본 서버, 인터랙션만 클라이언트
Action	폼이 부르는 서버 함수
Prisma	DB 쿼리를 타입과 함께
Clerk	로그인 + `userId`로 내 데이터만
Neon	배포용 Postgres
검색	상태는 URL 쿼리

다음에 공부하면 좋은 것

우선순위 예시:

테스트 — zod 스키마 / Action 단위 테스트
이미지 업로드 — 파일 저장·표시
권한·역할 — admin / member
캐시·성능 — fetch 옵션, 목록 페이지네이션
Auth.js — Clerk와 같은 구조를 직접 비교

새 시리즈를 쓴다면
“메모 앱 고도화” 또는 “포트폴리오용 기능 추가”로 끊는 편이 읽기 좋습니다.

마치며

이 시리즈의 목표는 문서를 다 외우는 게 아니었습니다.

작은 앱 하나를 만들고 → 저장하고 → 고치고 → 로그인하고 → 배포 이슈를 이해하는 것.

막힐 때마다 이 FAQ로 돌아와 보세요.
에러 메시지 한 줄이 보통 위 질문 중 하나에 연결됩니다.

질문·추가하고 싶은 FAQ가 있으면 댓글로 남겨 주세요.
같은 메모 앱 기준으로 이어서 정리할 수 있습니다.

전체 목차 (다시)

입문 1~8 · 실전 1~9
지금 이 글이 실전 시리즈의 매듭입니다.

저작자표시 (새창열림)

'frontend > NextJs' 카테고리의 다른 글

# [Next.js + TS 실전] 8. 목록 검색과 정렬 (1)	2026.07.31
# [Next.js + TS 실전] 7. 삭제 확인 UI (0)	2026.07.31
# [Next.js + TS 실전] 6. Neon Postgres 연결하기 (1)	2026.07.31
# [Next.js + TS 실전] 5. 로그인 붙이기 (Clerk) (0)	2026.07.30
# [Next.js + TS 실전] 4. 폼 검증하기 (zod) (0)	2026.07.30