More granular serverExternalPackages configuration

[AlessioGr]

Goals

Allow more granularity in serverExternalPackages to exclude / include only specific sub-path exports

Background

Next.js 16 support

Right now, we're unable to externalize our @payloadcms/storage-s3 package, because doing so also externalizes @payloadcms/storage-s3/client, which causes a runtime error.

However, if we don't externalize the root @payloadcms/storage-s3 export, we end up bundling @aws-sdk/client-s3 into the server build, which triggers a Turbopack warning on Next.js 15 and error on Next.js 16.

To resolve this, we'd need the ability to externalize @payloadcms/storage-s3 while keeping @payloadcms/storage-s3/client in the server bundle.

Performance Improvements

We recently improved Payload's compilation speed significantly by excluding server-only packages from bundling during development. The implementation looks like this:

serverExternalPackages: [
  // Exclude server-only packages from bundling during development to enhance compile speed
  ...(process.env.npm_lifecycle_event === 'dev'
    ? ['serveronlypkg', 'serveronlypkg2']
    : [])
]

This optimization resulted in a 50% faster compilation time for our users (from 4.1s down to 2.1s using Turbopack).

However, we currently face a limitation with packages that contain both client and server modules. For example:

• myPackage – server-only
• myPackage/client – client-only

At the moment, there's no granular way to exclude bundling myPackage while still ensuring that myPackage/client remains bundled. Allowing such granularity would enable us to further enhance compilation speed. At the moment, we are forced to keep bundling those packages.

Proposal

Allow more granular subpath exclusion in serverExternalPackages, e.g. by using ! to exclude only client modules

serverExternalPackages: [
  'myPackage',
  '!myPackage/client'
]

Or support glob patterns, though this may be tricky to implement in a non-breaking way, given that currently, specifying just the package will include all sub-path exports.