Multi-zones

Core Idea

Micro-frontend approach that splits one large domain into multiple independent Next.js applications ("zones"), each serving a distinct set of paths, deployed and developed separately but appearing as one site to the user.

Key Concepts

• Zone: a normal Next.js application configured with its own assetPrefix so its static assets don't collide with other zones' assets on the same domain.
• assetPrefix: next.config.js option that prefixes a zone's JS/CSS under /assetPrefix/_next/...; the default (catch-all) zone doesn't need one.
• Soft vs hard navigation: navigating within the same zone is a soft navigation (no reload); navigating across zones is a hard navigation (full resource reload).
• rewrites() for routing: the recommended way to route incoming paths to the correct zone's domain, minimizing latency versus a proxy.
• Proxy routing: alternative to rewrites when the zone decision must be dynamic (e.g. feature-flag-based migration).
• Cross-zone linking: must use a plain <a> tag, not <Link>, since <Link> tries to prefetch/soft-navigate relative paths, which fails across zone boundaries.
• serverActions.allowedOrigins: required config when using Server Actions with Multi-Zones, since the user-facing domain serves multiple apps.

Code Examples

// next.config.js — defining a zone's asset prefix
/** @type {import('next').NextConfig} */
const nextConfig = {
  assetPrefix: '/blog-static',
}

• O que demonstra: como isolar os assets estáticos de uma zona para não colidir com as demais.

// next.config.js — routing zones via rewrites in the entry app
async rewrites() {
    return [
        {
            source: '/blog',
            destination: `${process.env.BLOG_DOMAIN}/blog`,
        },
        {
            source: '/blog/:path+',
            destination: `${process.env.BLOG_DOMAIN}/blog/:path+`,
        },
        {
            source: '/blog-static/:path+',
            destination: `${process.env.BLOG_DOMAIN}/blog-static/:path+`,
        }
    ];
}

• O que demonstra: um app Next.js roteando requisições de path e de assets estáticos para o domínio de outra zona.

// proxy.js — dynamic zone routing decision
export async function proxy(request) {
  const { pathname, search } = request.nextUrl
  if (pathname === '/your-path' && myFeatureFlag.isEnabled()) {
    return NextResponse.rewrite(`${rewriteDomain}${pathname}${search}`)
  }
}

• O que demonstra: decisão dinâmica de roteamento entre zonas via proxy, útil para migração gradual controlada por feature flag.

Anti-patterns

• Duas zonas servindo o mesmo path: cria conflito de roteamento; paths precisam ser únicos por zona.
• Usar <Link> para navegar entre zonas: falha porque o prefetch/soft navigation não funciona cross-zone; usar <a>.
• Não configurar serverActions.allowedOrigins: Server Actions rejeitam a origem do domínio user-facing compartilhado entre zonas se não for explicitamente permitida.

Reference Tables

Not applicable — no tabular reference in source beyond the config snippets above.

Key Takeaways

1. Multi-Zones reduz tamanho de build e permite stacks/frameworks diferentes por zona, mas paga o custo de hard navigation ao cruzar zonas.
2. rewrites() é preferível a proxy para roteamento estático entre zonas por ter menor latência; proxy só quando a decisão precisa ser dinâmica.
3. Em Next.js 15+, não é mais necessário rewrite adicional para assets estáticos (_next/...); versões anteriores precisavam.
4. Zonas podem viver em repositórios separados ou num monorepo; monorepo facilita compartilhamento de código.
5. Feature flags ajudam a sincronizar releases entre zonas que são deployadas independentemente.

Connects To

• Multi-tenant (ch061): conceito próximo mas diferente, aponta para um template externo em vez de arquitetura própria de zonas.
• rewrites config: mecanismo central usado aqui para rotear paths entre zonas.