Font

Core Idea

next/font otimiza fontes automaticamente (Google Fonts ou arquivos locais) com self-hosting embutido: baixa CSS/arquivos em build time, elimina requests externos ao Google e evita layout shift, sem necessidade de instalar pacote adicional desde a v13.2.0.

Key Concepts

• next/font/google: importa qualquer Google Font como função; CSS e arquivos ficam self-hosted junto dos assets estáticos.
• next/font/local: carrega fonte local a partir de src (caminho ou array de {path, weight?, style?}).
• Fonte variável (variable font): não exige weight; caso contrário weight é obrigatório.
• className / style / CSS Variables: três formas de aplicar a fonte a um elemento.
• Font definitions file: arquivo central (ex. styles/fonts.ts) que define e reexporta instâncias de fonte, evitando recriar a mesma fonte em múltiplos lugares.
• Preloading: fonte só é preloaded nas rotas relacionadas (página específica) ou globalmente se declarada em pages/_app.js.

Code Examples

import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={inter.className}>
      <Component {...pageProps} />
    </main>
  )
}

• O que demonstra: aplicação global da fonte via _app.js, sem especificar weight (fonte variável).

import { Roboto } from 'next/font/google'

const roboto = Roboto({ weight: '400', subsets: ['latin'] })

• O que demonstra: fonte não-variável exige weight explícito; pode ser array (weight: ['400', '700'], style: ['normal', 'italic']).

import localFont from 'next/font/local'

const roboto = localFont({
  src: [
    { path: './Roboto-Regular.woff2', weight: '400', style: 'normal' },
    { path: './Roboto-Bold.woff2', weight: '700', style: 'normal' },
  ],
})

• O que demonstra: múltiplos arquivos locais para a mesma família de fonte via array em src.

const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
const roboto_mono = Roboto_Mono({ subsets: ['latin'], variable: '--font-roboto-mono' })

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={`${inter.variable} ${roboto_mono.variable} font-sans`}>
      <Component {...pageProps} />
    </main>
  )
}

• O que demonstra: integração com Tailwind CSS via CSS variables, consumidas em @theme inline (v4) ou tailwind.config.js (v3).

Reference Tables

Opção	font/google	font/local	Tipo	Obrigatório
src	não	sim	String ou Array de Objetos	Sim (local)
weight	sim	sim	String ou Array	Obrigatório se não-variável
style	sim	sim	String ou Array	-
subsets	sim	não	Array de Strings	-
axes	sim	não	Array de Strings	-
display	sim	sim	String (default 'swap')	-
preload	sim	sim	Boolean (default true)	-
fallback	sim	sim	Array de Strings	-
adjustFontFallback	sim	sim	Boolean ou String	-
variable	sim	sim	String	-
declarations	não	sim	Array de Objetos	-

Anti-patterns

• Múltiplas fontes sem necessidade: cada fonte adicional é um recurso extra que o cliente baixa; usar com moderação.
• Fonte não-variável sem weight: erro de configuração — variável é obrigatória quando a fonte não é variable font.
• Nome de fonte com espaço sem underscore: Roboto Mono deve ser importado como Roboto_Mono.

Key Takeaways

1. Zero requests ao Google em runtime — tudo é baixado em build time e self-hosted.
2. weight só é opcional para variable fonts; caso contrário é obrigatório.
3. CSS Variables (variable option) é o caminho recomendado para integração com Tailwind CSS.
4. Font definitions file evita recarregar a mesma fonte como múltiplas instâncias no bundle.
5. Desde v13.2.0 o pacote é next/font embutido, sem instalação (@next/font foi renomeado).

Connects To

• Custom App (pages/_app.js): local típico para aplicar fonte globalmente no Pages Router.
• CSS / Tailwind CSS: consumo das CSS variables geradas pela opção variable.