Next.js 16 빌드가 default.js 누락으로 멈출 때, parallel route 슬롯을 채우는 법

Next.js 16으로 올린 뒤 parallel route가 있는 앱의 next build가 default.js 누락 때문에 멈출 수 있다. 개발 중 링크 이동은 되는데 production build나 새로고침에서만 문제가 드러난다면 상태 코드보다 app 폴더의 모든 @slot과 default.tsx를 먼저 대조한다.

Next.js 16 업그레이드 공식 문서는 모든 parallel route 슬롯에 명시적 default.js가 필요하며 없으면 빌드가 실패한다고 안내한다. 해결은 모든 파일에 같은 코드를 넣는 일이 아니다. 누락 위치를 찾고 그 슬롯이 404를 보여야 하는지, 아무것도 렌더링하지 않아야 하는지 결정한 뒤 build와 full reload를 함께 확인해야 한다.

Tap to zoom

default.tsx는 새로고침에서 잃어버린 슬롯 상태를 대신한다

Parallel Routes 공식 문서에 따르면 @analytics, @modal 같은 폴더는 URL segment가 아니라 같은 layout에 전달되는 named slot이다. 클라이언트 링크로 이동하는 soft navigation에서는 Next.js가 각 slot의 active state를 기억한다.

브라우저 새로고침이나 주소 직접 입력 같은 hard navigation에서는 상황이 달라진다. 현재 URL과 맞지 않는 slot의 이전 상태를 복구할 수 없어 default.tsx를 렌더링한다. Next.js 16에서는 이 fallback을 모든 parallel route slot에 명시해야 build를 통과한다. children도 폴더 이름이 보이지 않을 뿐 implicit slot이므로 부모 구조에 따라 함께 확인한다.

Tap to zoom

layout이 받는 prop에서 누락된 @slot을 찾는다

오류 메시지만 보고 아무 폴더에 default.tsx를 추가하지 않는다. 먼저 app 아래의 @ 폴더와 그 부모 layout.tsx가 받는 prop을 나란히 본다.

app/
  dashboard/
    @analytics/
      page.tsx
      default.tsx
    @team/
      settings/page.tsx
      ← default.tsx 누락
    layout.tsx
    page.tsx

PowerShell에서는 다음 명령으로 slot 폴더와 default 파일을 함께 찾을 수 있다.

Get-ChildItem app -Recurse -Directory | Where-Object Name -Like '@*'
Get-ChildItem app -Recurse -File -Include default.js,default.jsx,default.tsx

macOS나 Linux에서는 프로젝트 검색이나 find app -type d -name '@*'로 같은 목록을 얻는다. 이어서 부모 layout의 team, analytics, modal 같은 prop과 폴더를 비교한다. 생성된 타입 경로만 보여 원본을 찾기 어렵다면 .next/types에서 원본 route를 찾는 순서로 실제 app 파일까지 거슬러 올라간다.

notFound()와 null은 사용자에게 보일 결과로 고른다

default.js 공식 레퍼런스는 이전의 404 동작을 유지하려면 notFound()를 호출하는 fallback을 만들 수 있다고 설명한다.

import { notFound } from 'next/navigation'

export default function Default() {
  notFound()
}

반면 intercepted route로 여는 모달처럼 해당 slot이 활성화되지 않았을 때 아무것도 보여주지 않는 것이 맞다면 null을 반환한다.

export default function Default() {
  return null
}

모든 slot에 null을 복사하면 빌드는 통과해도 필요한 fallback 화면까지 숨길 수 있다. 각 slot이 “없어도 되는 보조 UI”인지, “경로가 맞지 않음을 알려야 하는 영역”인지 한 문장으로 적고 코드를 고른다.

build와 full reload를 같은 수정에서 검증한다

Tap to zoom

파일을 추가한 뒤에는 개발 서버만 보지 말고 production build를 다시 실행한다.

npm run build

빌드가 통과하면 parallel route가 갈리는 URL을 브라우저 주소창에 직접 입력하고 새로고침한다. 다음 네 결과를 남긴다.

• 모든 @slot에 의도한 default.tsx가 있다.
• soft navigation에서 기존 slot 상태가 유지된다.
• hard navigation에서 null, fallback UI, 404 중 선택한 결과가 보인다.
• production build가 같은 커밋에서 통과한다.

개발은 되는데 build에서만 다른 오류가 이어진다면 useSearchParams 때문에 빌드가 실패하는 경우의 Suspense 점검처럼 첫 구체적 오류를 새 문제로 분리한다. 이번 수정의 완료 기준은 경고가 줄어드는 것이 아니라 누락 slot이 없어지고 build와 새로고침 결과가 함께 맞는 것이다.

참고 출처

• Upgrading to Next.js 16 (Next.js)
• Parallel Routes (Next.js)
• default.js (Next.js)
• Next.js 16 release (Next.js)

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.