Next.js viewport 설정 오류 해결: "Unsupported metadata viewport"

Next.js에서 뷰포트(viewport)를 설정하려다가 "Unsupported metadata viewport" 오류를 만난다면?
최근 Next.js 업데이트로 인해 기존의 metadata.viewport 방식이 더 이상 지원되지 않기 때문!
지금부터 오류 원인과 해결 방법을 정리해보겠습니다. 😊

---

export const metadata: Metadata = {
    title: "Create Next App",
    description: "Generated by create next app",
    viewport: "width=360, height=800, initial-scale=1, user-scalable=no",
};

Next.js layout.tsx에서 위처럼 metadata.viewport을 설정하면 지원되지 않는다는 경고가 발생합니다.

그러면 다음과 같은 경고 문구가 표시되고,

⚠ Unsupported metadata viewport is configured in metadata export in /. 
Please move it to viewport export instead.

문구를 통해
❌ metadata.viewport은 더 이상 지원되지 않으며, 다른 방식으로 설정해야 한다는걸 알 수 있습니다.

---

Next.js에서는 viewport를 별도의 export const viewport로 선언해야 정상적으로 적용됩니다.

// ✅ `metadata`에 viewport 제거
export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

// ✅ 최신 방식으로 viewport 설정
export const viewport = {
  width: "device-width",
  initialScale: 1,
  userScalable: "no",
};

 

360x800 크기의 앱 화면을 구성하기 위해서, width의 값은 사람들 사용하는 장치의 넓이 값을 기본으로 주었고, height값은 굳이 설정을 안해도 되겠더라고요,

그리고 앱에서 화면을 확대하거나 축소할 일은 없어서 userScalable값을 no로 주어서 미리 막아두고, 기본 크기는 1배로 설정해두었습니다.

---

실행 후 정상적으로 적용되는지 확인하기 위해서,

 

• Windows/Linux: F12 또는 Ctrl + Shift + I
• Mac: Cmd + Option + I

를 실행한 후, crtl + shift + m 을 눌러 앱 화면 모드로 전환해서 크기를 확인합니다.

정상적으로 적용된 것을 확인할 수 있습니다!