favicon, icon, and apple-icon

Core Idea

Convenções de arquivo para definir ícones do app (aba do navegador, home screen, resultados de busca) via imagem estática ou código gerador.

Key Concepts

• favicon: só .ico, só no nível raiz de app/.
• icon: .ico, .jpg, .jpeg, .png, .svg; pode estar em qualquer segmento (app/**/*).
• apple-icon: .jpg, .jpeg, .png; pode estar em qualquer segmento.
• Geração por código: icon.(js|ts|tsx) ou apple-icon.(js|ts|tsx) default-exportando uma função, tipicamente usando ImageResponse de next/og.
• size e contentType: exports opcionais para configurar metadata do ícone gerado.
• Múltiplos ícones: sufixo numérico no nome (icon1.png, icon2.png), ordenados lexicamente.

Code Examples

import { ImageResponse } from 'next/og'

export const size = { width: 32, height: 32 }
export const contentType = 'image/png'

export default function Icon() {
  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 24,
          background: 'black',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
        }}
      >
        A
      </div>
    ),
    { ...size }
  )
}

• O que demonstra: geração de ícone dinâmico via ImageResponse, reaproveitando size nas opções de render.

export default async function Icon({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
}

• O que demonstra: ícone gerado recebe params do segmento onde está colocado (desde v16, é promise).

Reference Tables

File convention	Tipos suportados (imagem)	Localização válida
favicon	.ico	app/ (raiz apenas)
icon	.ico, .jpg, .jpeg, .png, .svg	app/**/*
apple-icon	.jpg, .jpeg, .png	app/**/*

File convention (código)	Tipos suportados
icon	.js, .ts, .tsx
apple-icon	.js, .ts, .tsx

Anti-patterns

• Tentar gerar um favicon via código: não é possível; use icon ou um favicon.ico estático.
• Colocar favicon fora do nível raiz de app/: só funciona no topo; para granularidade por segmento, use icon.

Key Takeaways

1. Ícones gerados são estaticamente otimizados (build time, cacheados) a menos que usem Request-time APIs ou dados não-cacheados.
2. generateImageMetadata permite gerar múltiplos ícones no mesmo arquivo.
3. icon/apple-icon são Route Handlers especializados que aceitam as mesmas opções de Route Segment Config de pages/layouts.
4. Atributos <link> (rel, type, sizes) são inferidos automaticamente do arquivo avaliado.

Connects To

• ImageResponse: API usada para gerar ícones/imagens via código.
• generateImageMetadata: gera múltiplas variantes de ícone/imagem no mesmo arquivo.
• manifest.json: outra fonte de ícones para PWA/home screen.