basePath

Core Idea

Config option to deploy a Next.js app under a sub-path of a domain (e.g. /docs), automatically applied to next/link/next/router links and requiring manual prefixing for next/image sources.

Key Concepts

• basePath: Prefixo de path para toda a aplicação; deve ser setado em build time (é inlined nos bundles client-side — não pode mudar sem rebuild).

Code Examples

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

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

• O que demonstra: Com basePath: '/docs', um href="/about" é automaticamente reescrito para /docs/about no HTML gerado.

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: Ao contrário de <Link>, next/image exige que você prefixe src manualmente com o basePath.

Anti-patterns

• Esperar que next/image aplique o basePath automaticamente: não aplica; o src precisa incluir o prefixo manualmente.
• Mudar basePath sem rebuild: o valor é inlined nos bundles client-side em build time.

Key Takeaways

1. <Link>/next/router aplicam basePath automaticamente, evitando reescrever todos os links da app.
2. next/image é uma exceção: src precisa incluir o prefixo manualmente.
3. Valor padrão é string vazia ''.

Connects To

• assetPrefix: alternativa para servir assets via CDN em vez de sub-path.
• next/link, next/image: componentes cujo comportamento com basePath diverge (automático vs. manual).