basePath

Core Idea

Configura um prefixo de path fixo para deployar a aplicação inteira sob um sub-path de domínio (ex.: /docs).

Key Concepts

• basePath: string de prefixo aplicado a todas as rotas; padrão ''
• Aplicação automática em links: next/link e next/router aplicam basePath automaticamente
• Aplicação manual em next/image: src precisa incluir o basePath manualmente

Code Examples

module.exports = {
  basePath: '/docs',
}

• O que demonstra: configuração básica do prefixo.

export default function HomePage() {
  return (
    <>
      <Link href="/about">About Page</Link>
    </>
  )
}

• O que demonstra: href="/about" vira automaticamente <a href="/docs/about"> no HTML de saída.

import Image from 'next/image'

function Home() {
  return (
    <Image src="/docs/me.png" alt="Picture of the author" width={500} height={500} />
  )
}

• O que demonstra: next/image exige o basePath explícito no src, diferente de next/link.

Anti-patterns

• Mudar basePath sem rebuild: o valor é inlined nos bundles client-side em build time, alterar exige novo build
• Esquecer o prefixo em src de next/image: causa 404 de imagem, já que Image não aplica basePath automaticamente

Key Takeaways

1. basePath deve ser definido em build time, é fixo até novo build
2. Links via next/link/next/router recebem o prefixo automaticamente, sem precisar reescrever cada href
3. next/image é exceção: src precisa do prefixo manual

Connects To

• assetPrefix (ch391): opção separada para CDN, não confundir propósito