문서
App Router 사용하기
API 참조
파일 구성 규칙
메타데이터
파비콘, 아이콘, 애플 아이콘

파비콘, 아이콘, 그리고 애플 아이콘

favicon, icon, 또는 apple-icon 파일 규칙을 사용하면 애플리케이션의 아이콘을 설정할 수 있습니다.

이는 웹 브라우저 탭, 휴대폰 홈 화면 및 검색 엔진 결과와 같은 곳에 나타나는 앱 아이콘을 추가하는 데 유용합니다.

앱 아이콘을 설정하는 두 가지 방법이 있습니다:

이미지 파일 (.ico, .jpg, .png)

/app 디렉토리 내에 favicon, icon, 또는 apple-icon 이미지 파일을 배치하여 앱 아이콘을 설정할 수 있습니다. favicon 이미지는 app/의 최상위 레벨에만 위치할 수 있습니다.

Next.js는 파일을 평가하고 자동으로 적절한 태그를 앱의 <head> 요소에 추가합니다.

파일 규칙지원되는 파일 형식유효한 위치
favicon.icoapp/
icon.ico, .jpg, .jpeg, .png, .svgapp/**/*
apple-icon.jpg, .jpeg, .pngapp/**/*

favicon

루트 /app 라우트 세그먼트에 favicon.ico 이미지 파일을 추가합니다.

<head> output
<link rel="icon" href="/favicon.ico" sizes="any" />

icon

icon.(ico|jpg|jpeg|png|svg) 이미지 파일을 추가합니다.

<head> output
<link
  rel="icon"
  href="/icon?<generated>"
  type="image/<generated>"
  sizes="<generated>"
/>

apple-icon

apple-icon.(jpg|jpeg|png) 이미지 파일을 추가합니다.

<head> output
<link
  rel="apple-touch-icon"
  href="/apple-icon?<generated>"
  type="image/<generated>"
  sizes="<generated>"
/>

알아두면 좋은 점

  • 파일 이름에 숫자 접미사를 추가하여 여러 아이콘을 설정할 수 있습니다. 예: icon1.png, icon2.png 등. 번호가 매겨진 파일은 사전식으로 정렬됩니다.
  • Favicon은 루트 /app 세그먼트에서만 설정할 수 있습니다. 더 세분화된 제어가 필요한 경우 icon을 사용할 수 있습니다.
  • 적절한 <link> 태그와 rel, href, type, sizes와 같은 속성은 아이콘 유형과 평가된 파일의 메타데이터에 따라 결정됩니다.
    • 예를 들어, 32x32 픽셀의 .png 파일은 type="image/png" 및 sizes="32x32" 속성을 갖게 됩니다.
  • .ico 아이콘이 .svg보다 선호되는 브라우저 버그를 피하기 위해 favicon.ico 출력에 sizes="any"가 추가됩니다.

코드를 사용하여 아이콘 생성하기 (.js, .ts, .tsx)

실제 이미지 파일을 사용하는 것 외에도, 코드를 사용하여 프로그래밍 방식으로 아이콘을 생성할 수 있습니다.

함수를 기본 내보내는 icon 또는 apple-icon 라우트를 생성하여 앱 아이콘을 생성할 수 있습니다.

파일 규칙지원되는 파일 형식
icon.js, .ts, .tsx
apple-icon.js, .ts, .tsx

아이콘을 생성하는 가장 쉬운 방법은 next/og의 ImageResponse API를 사용하는 것입니다.

app/icon.tsx
import { ImageResponse } from "next/og";
 
// 이미지 메타데이터
export const size = {
  width: 32,
  height: 32,
};
export const contentType = "image/png";
 
// 이미지 생성
export default function Icon() {
  return new ImageResponse(
    (
      // ImageResponse JSX 요소
      <div
        style={{
          fontSize: 24,
          background: "black",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          color: "white",
        }}
      >
        A
      </div>
    ),
    // ImageResponse 옵션
    {
      // 편의를 위해 내보낸 아이콘 크기 메타데이터 설정을
      // ImageResponse의 너비와 높이를 설정하는 데도 재사용할 수 있습니다.
      ...size,
    }
  );
}
app/icon.js
import { ImageResponse } from "next/og";
 
// 이미지 메타데이터
export const size = {
  width: 32,
  height: 32,
};
export const contentType = "image/png";
 
// 이미지 생성
export default function Icon() {
  return new ImageResponse(
    (
      // ImageResponse JSX 요소
      <div
        style={{
          fontSize: 24,
          background: "black",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          color: "white",
        }}
      >
        A
      </div>
    ),
    // ImageResponse 옵션
    {
      // 편의를 위해 내보낸 아이콘 크기 메타데이터 설정을
      // ImageResponse의 너비와 높이를 설정하는 데도 재사용할 수 있습니다.
      ...size,
    }
  );
}
<head> output
<link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />

알아두면 좋은 점

  • 기본적으로 생성된 아이콘은 동적 함수나 캐시되지 않은 데이터를 사용하지 않는 한 정적으로 최적화됩니다(빌드 시 생성되고 캐시됨).
  • generateImageMetadata를 사용하여 동일한 파일에서 여러 아이콘을 생성할 수 있습니다.
  • favicon 아이콘은 생성할 수 없습니다. 대신 icon 또는 favicon.ico 파일을 사용하세요.
  • 앱 아이콘은 동적 함수나 동적 config 옵션을 사용하지 않는 한 기본적으로 캐시되는 특별한 Route Handler입니다.

Props

기본 내보내기 함수는 다음과 같은 props를 받습니다:

params (선택사항)

루트 세그먼트부터 icon 또는 apple-icon이 위치한 세그먼트까지의 동적 라우트 매개변수 객체를 포함하는 객체입니다.

app/shop/[slug]/icon.tsx
export default function Icon({ params }: { params: { slug: string } }) {
  // ...
}
app/shop/[slug]/icon.js
export default function Icon({ params }) {
  // ...
}
라우트URLparams
app/shop/icon.js/shopundefined
app/shop/[slug]/icon.js/shop/1{ slug: '1' }
app/shop/[tag]/[item]/icon.js/shop/1/2{ tag: '1', item: '2' }

반환

기본 내보내기 함수는 Blob | ArrayBuffer | TypedArray | DataView | ReadableStream | Response를 반환해야 합니다.

알아두면 좋은 점: ImageResponse는 이 반환 타입을 만족합니다.

Config 내보내기

선택적으로 icon 또는 apple-icon 라우트에서 size와 contentType 변수를 내보내어 아이콘의 메타데이터를 구성할 수 있습니다.

옵션타입
size{ width: number; height: number }
contentTypestring - 이미지 MIME 타입

size

icon.tsx | apple-icon.tsx
export const size = { width: 32, height: 32 };
 
export default function Icon() {}
icon.js | apple-icon.js
export const size = { width: 32, height: 32 };
 
export default function Icon() {}
<head> output
<link rel="icon" sizes="32x32" />

contentType

icon.tsx | apple-icon.tsx
export const contentType = "image/png";
 
export default function Icon() {}
icon.js | apple-icon.js
export const contentType = "image/png";
 
export default function Icon() {}
<head> output
<link rel="icon" type="image/png" />

라우트 세그먼트 설정

icon과 apple-icon은 Pages와 Layouts와 동일한 라우트 세그먼트 구성 옵션을 사용할 수 있는 특수한 Route Handlers입니다.

버전 기록

버전변경 사항
v13.3.0favicon icon 및 apple-icon 도입
메타데이터manifest.json