Melhores Práticas de Imagens e Ícones

Um resumo condensado das 25 melhores práticas mais importantes, extraídas de todas as páginas desta seção.

Prefira next/image em vez de img: Use next/image para que o Next.js sirva automaticamente WebP/AVIF, carregue imagens fora da tela (lazy-loads) e gere tamanhos responsivos. A tag <img> bruta não oferece otimização e prejudica o LCP.
Sempre combine fill com sizes: Usar fill sem uma prop sizes faz com que o navegador baixe a maior variante para cada dispositivo. Forneça uma string sizes consciente de breakpoints que corresponda às suas colunas de layout reais.
Defina position: relative nos Pais de fill: O pai de uma imagem fill deve ter position: relative (ou absolute/fixed) mais dimensões definidas, ou a imagem colapsará para altura zero. Use um wrapper de proporção para travar o layout.
Reserve priority para Imagens LCP: Adicione priority apenas a imagens de destaque acima da dobra (geralmente uma ou duas por página). O uso excessivo cancela o benefício de lazy-loading do next/image.
Configure remotePatterns Explicitamente: Adicione todos os hosts de imagem externos (por exemplo, images.unsplash.com, images.pexels.com, cdn.pixabay.com) a images.remotePatterns em next.config.ts e reinicie o servidor de desenvolvimento. Entradas ausentes causam erros 400 em tempo de execução, não em tempo de compilação.
Prefira Importações Estáticas para Imagens Locais: Importações estáticas retornam StaticImageData com width, height e um blurDataURL gerado automaticamente, eliminando boilerplate manual. Elas também habilitam placeholder="blur" sem trabalho extra.
Use width/height Apenas para Proporção: As props width e height definem o tamanho e a proporção solicitados - elas não redimensionam ou cortam o elemento renderizado. Controle o dimensionamento visual com classes CSS.
Nunca Exponha Chaves de API no Navegador: Chaves do Unsplash, Pexels e Pixabay devem permanecer no lado do servidor; busque de Server Components ou Route Handlers e armazene segredos em .env.local. O Pixabay é especialmente arriscado porque a chave é um parâmetro de consulta.
Armazene em Cache Respostas de API com revalidate: Envolva as buscas de fotos de estoque com next: { revalidate: 3600 } para permanecer dentro dos limites de taxa horários (Unsplash 50/5000, Pexels 200, Pixabay 100/min) e manter as páginas rápidas. Isso também evita sobrecarregar APIs de terceiros em cada solicitação.
Use o Formato Correto do Cabeçalho de Autenticação: O Unsplash requer Authorization: Client-ID <key>, o Pexels requer a chave bruta sem o prefixo Bearer, e o Pixabay usa um parâmetro de consulta key. Misturar isso retorna um 401 e desperdiça tempo de depuração.
Escolha o Tamanho de URL Correto: Use regular/webformatURL/large para exibição e reserve raw/original/fullHDURL para downloads, pois os originais podem exceder 10MB. Servir imagens superdimensionadas anula o propósito de um pipeline de otimização.
Respeite a Atribuição e o Rastreamento de Downloads: O Unsplash exige crédito ao fotógrafo com parâmetros UTM e uma chamada para download_location sempre que uma foto é usada. Pexels e Pixabay incentivam fortemente a atribuição, mesmo quando não é estritamente necessário.
Trate o Texto Alt da API como Não Confiável: Campos como alt do Pexels ou alt_description do Unsplash podem estar vazios, genéricos ou nulos. Forneça um fallback significativo para manter as imagens acessíveis.
Nunca Faça Hotlink do Pixabay em Produção: A licença do Pixabay permite apenas hotlinking temporário de CDN; para produção, baixe e hospede as imagens em sua própria infraestrutura. Planeje um passo de compilação ou um pipeline de ingestão de acordo.
Importe Ícones de Sub-Caminhos de Família: Sempre importe react-icons de um caminho de família como react-icons/fa - importar da raiz do pacote pode prejudicar o tree-shaking e incluir milhares de ícones não utilizados. A mesma disciplina se aplica a qualquer importação de ícones em estilo de barril.
Estilize Heroicons Apenas com className: Heroicons ignora as props size e color; defina dimensões e cores com utilitários Tailwind como h-6 w-6 text-blue-500. Alias importações ao usar variantes outline e solid do mesmo ícone em um arquivo.
Tipifique Ícones como Componentes, Não Elementos: Use LucideIcon, IconType ou React.ComponentType<SVGProps<SVGSVGElement>> para tipificar props de ícones para que você possa renderizá-los com <Icon size={…} />. Passar um elemento renderizado em vez de um tipo de componente quebra wrappers de botão reutilizáveis.
Marque Provedores IconContext como Cliente: IconContext.Provider do react-icons usa React Context e deve residir em um Client Component no App Router. Coloque-o alto o suficiente na árvore para cobrir a subárvore que você deseja estilizar.
Use currentColor para SVGs Personalizados: Defina stroke="currentColor" (ou fill="currentColor") em ícones SVG inline para que eles herdem a cor através das classes text-* do pai. Isso faz com que um conjunto de ícones criado manualmente se comporte como Lucide ou Heroicons.
Torne a Acessibilidade SVG Explícita: Ícones decorativos devem ter aria-hidden="true" e nenhum role; ícones informativos precisam de role="img" mais um aria-label. Também escreva atributos SVG em camelCase (viewBox, strokeWidth) e mantenha viewBox mesmo após a otimização SVGO.
Defina fill e stroke Padrões Intencionalmente: Os padrões SVG fill e stroke são preto, então ícones baseados em traço precisam de fill="none" e ícones preenchidos precisam de stroke="none" para evitar renderização surpresa. O comportamento apenas de traço do Lucide é um exemplo concreto - fill não tem efeito lá.
Gere blurDataURLs em Tempo de Compilação: Produza BlurHash ou pequenos JPEGs blurDataURL (cerca de 8x8 pixels) com antecedência e armazene-os em cache com seus metadados de imagem. Gerá-los por solicitação com sharp adiciona latência e não pode ser executado no Edge Runtime.
Combine as Dimensões do Esqueleto com o Conteúdo Final: Esqueletos de "shimmer" ou proporção devem usar a mesma proporção da imagem carregada para que o layout não mude (CLS). Aplique blur() CSS apenas a placeholders minúsculos, nunca a imagens de resolução total.
Siga as Convenções de Arquivo de Metadados do Next.js: Coloque favicon.ico na raiz app/, e solte icon.*, apple-icon.*, opengraph-image.* e twitter-image.* nos segmentos de rota onde eles devem se aplicar. O Next.js os insere automaticamente no <head> e escopa as imagens OG por rota.
Projete Imagens OG em Torno dos Limites do Satori: ImageResponse do next/og usa Satori, que suporta apenas flexbox (sem grid), sem background-image: url(), e requer fontes carregadas como ArrayBuffer. Mire em 1200x630, exporte um alt, e prefira runtime = "edge" para imagens rápidas e armazenáveis em cache por página.

Prefira next/image em vez de img: Use next/image para que o Next.js sirva automaticamente WebP/AVIF, carregue imagens fora da tela (lazy-loads) e gere tamanhos responsivos. A tag <img> bruta não oferece otimização e prejudica o LCP.
Sempre combine fill com sizes: Usar fill sem uma prop sizes faz com que o navegador baixe a maior variante para cada dispositivo. Forneça uma string sizes consciente de breakpoints que corresponda às suas colunas de layout reais.
Defina position: relative nos Pais de fill: O pai de uma imagem fill deve ter position: relative (ou absolute/fixed) mais dimensões definidas, ou a imagem colapsará para altura zero. Use um wrapper de proporção para travar o layout.
Reserve priority para Imagens LCP: Adicione priority apenas a imagens de destaque acima da dobra (geralmente uma ou duas por página). O uso excessivo cancela o benefício de lazy-loading do next/image.
Configure remotePatterns Explicitamente: Adicione todos os hosts de imagem externos (por exemplo, images.unsplash.com, images.pexels.com, cdn.pixabay.com) a images.remotePatterns em next.config.ts e reinicie o servidor de desenvolvimento. Entradas ausentes causam erros 400 em tempo de execução, não em tempo de compilação.
Prefira Importações Estáticas para Imagens Locais: Importações estáticas retornam StaticImageData com width, height e um blurDataURL gerado automaticamente, eliminando boilerplate manual. Elas também habilitam placeholder="blur" sem trabalho extra.
Use width/height Apenas para Proporção: As props width e height definem o tamanho e a proporção solicitados - elas não redimensionam ou cortam o elemento renderizado. Controle o dimensionamento visual com classes CSS.
Nunca Exponha Chaves de API no Navegador: Chaves do Unsplash, Pexels e Pixabay devem permanecer no lado do servidor; busque de Server Components ou Route Handlers e armazene segredos em .env.local. O Pixabay é especialmente arriscado porque a chave é um parâmetro de consulta.
Armazene em Cache Respostas de API com revalidate: Envolva as buscas de fotos de estoque com next: { revalidate: 3600 } para permanecer dentro dos limites de taxa horários (Unsplash 50/5000, Pexels 200, Pixabay 100/min) e manter as páginas rápidas. Isso também evita sobrecarregar APIs de terceiros em cada solicitação.
Use o Formato Correto do Cabeçalho de Autenticação: O Unsplash requer Authorization: Client-ID <key>, o Pexels requer a chave bruta sem o prefixo Bearer, e o Pixabay usa um parâmetro de consulta key. Misturar isso retorna um 401 e desperdiça tempo de depuração.
Escolha o Tamanho de URL Correto: Use regular/webformatURL/large para exibição e reserve raw/original/fullHDURL para downloads, pois os originais podem exceder 10MB. Servir imagens superdimensionadas anula o propósito de um pipeline de otimização.
Respeite a Atribuição e o Rastreamento de Downloads: O Unsplash exige crédito ao fotógrafo com parâmetros UTM e uma chamada para download_location sempre que uma foto é usada. Pexels e Pixabay incentivam fortemente a atribuição, mesmo quando não é estritamente necessário.
Trate o Texto Alt da API como Não Confiável: Campos como alt do Pexels ou alt_description do Unsplash podem estar vazios, genéricos ou nulos. Forneça um fallback significativo para manter as imagens acessíveis.
Nunca Faça Hotlink do Pixabay em Produção: A licença do Pixabay permite apenas hotlinking temporário de CDN; para produção, baixe e hospede as imagens em sua própria infraestrutura. Planeje um passo de compilação ou um pipeline de ingestão de acordo.
Importe Ícones de Sub-Caminhos de Família: Sempre importe react-icons de um caminho de família como react-icons/fa - importar da raiz do pacote pode prejudicar o tree-shaking e incluir milhares de ícones não utilizados. A mesma disciplina se aplica a qualquer importação de ícones em estilo de barril.
Estilize Heroicons Apenas com className: Heroicons ignora as props size e color; defina dimensões e cores com utilitários Tailwind como h-6 w-6 text-blue-500. Alias importações ao usar variantes outline e solid do mesmo ícone em um arquivo.
Tipifique Ícones como Componentes, Não Elementos: Use LucideIcon, IconType ou React.ComponentType<SVGProps<SVGSVGElement>> para tipificar props de ícones para que você possa renderizá-los com <Icon size={…} />. Passar um elemento renderizado em vez de um tipo de componente quebra wrappers de botão reutilizáveis.
Marque Provedores IconContext como Cliente: IconContext.Provider do react-icons usa React Context e deve residir em um Client Component no App Router. Coloque-o alto o suficiente na árvore para cobrir a subárvore que você deseja estilizar.
Use currentColor para SVGs Personalizados: Defina stroke="currentColor" (ou fill="currentColor") em ícones SVG inline para que eles herdem a cor através das classes text-* do pai. Isso faz com que um conjunto de ícones criado manualmente se comporte como Lucide ou Heroicons.
Torne a Acessibilidade SVG Explícita: Ícones decorativos devem ter aria-hidden="true" e nenhum role; ícones informativos precisam de role="img" mais um aria-label. Também escreva atributos SVG em camelCase (viewBox, strokeWidth) e mantenha viewBox mesmo após a otimização SVGO.
Defina fill e stroke Padrões Intencionalmente: Os padrões SVG fill e stroke são preto, então ícones baseados em traço precisam de fill="none" e ícones preenchidos precisam de stroke="none" para evitar renderização surpresa. O comportamento apenas de traço do Lucide é um exemplo concreto - fill não tem efeito lá.
Gere blurDataURLs em Tempo de Compilação: Produza BlurHash ou pequenos JPEGs blurDataURL (cerca de 8x8 pixels) com antecedência e armazene-os em cache com seus metadados de imagem. Gerá-los por solicitação com sharp adiciona latência e não pode ser executado no Edge Runtime.
Combine as Dimensões do Esqueleto com o Conteúdo Final: Esqueletos de "shimmer" ou proporção devem usar a mesma proporção da imagem carregada para que o layout não mude (CLS). Aplique blur() CSS apenas a placeholders minúsculos, nunca a imagens de resolução total.
Siga as Convenções de Arquivo de Metadados do Next.js: Coloque favicon.ico na raiz app/, e solte icon.*, apple-icon.*, opengraph-image.* e twitter-image.* nos segmentos de rota onde eles devem se aplicar. O Next.js os insere automaticamente no <head> e escopa as imagens OG por rota.
Projete Imagens OG em Torno dos Limites do Satori: ImageResponse do next/og usa Satori, que suporta apenas flexbox (sem grid), sem background-image: url(), e requer fontes carregadas como ArrayBuffer. Mire em 1200x630, exporte um alt, e prefira runtime = "edge" para imagens rápidas e armazenáveis em cache por página.

Melhores Práticas de Imagens e Ícones

Buscar na documentação

Melhores Práticas de Imagens e Ícones