serverExternalPackages

Core Idea

Opts specific dependencies out of the automatic bundling performed by bundlePagesRouterDependencies, forcing Next.js to resolve them via native Node.js require instead.

Key Concepts

• serverExternalPackages: array of package names in next.config.js to exclude from bundling for the Pages Router.
• Default opt-out list: Next.js already excludes a fixed list of popular packages known to have bundling compatibility issues (native bindings, dynamic requires, etc).

Code Examples

/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: ['@acme/ui'],
}

module.exports = nextConfig

• O que demonstra: força um pacote customizado a ser resolvido via require nativo em vez de bundlado.

Reference Tables

Já excluídos por padrão (parcial, lista extensa): @prisma/client, bcrypt, sharp, puppeteer, puppeteer-core, playwright, playwright-core, sqlite3, better-sqlite3, mongodb, mongoose, pg, canvas, @aws-sdk/client-s3, firebase-admin, express, webpack, typescript, eslint, jest, cypress, entre outros (~60 pacotes ao todo, tipicamente libs com bindings nativos, ferramentas de build/test, ou clientes de banco).

Anti-patterns

• Tentar bundlar pacotes com binding nativo (ex: sharp, bcrypt): causa falhas em runtime, por isso já vêm excluídos por padrão.

Key Takeaways

1. Só use serverExternalPackages manualmente quando um pacote seu apresenta erro de bundling e não está na lista default.
2. É complementar ao bundlePagesRouterDependencies (que liga o bundling automático no Pages Router).

Connects To

• bundlePagesRouterDependencies: config que este opção faz opt-out de.
• output (standalone): interage com quais dependências acabam no bundle final de deploy.