supportsImmutableAssets

Core Idea

Config option aimed at adapter authors: controls whether Next.js omits the ?dpl=<deployment-id> query parameter on static asset URLs when skew protection is enabled and the deployment provider supports content-addressed, immutable static assets.

Key Concepts

• supportsImmutableAssets: boolean; when the adapter has enabled support for immutable static assets, set to false to opt out of that behavior. Has no effect if the adapter has not enabled the feature.
• Skew protection: normally appends ?dpl=<unique-deployment-id> to static asset requests, forcing re-download after every deploy even if the asset content is unchanged.
• Immutable static assets: served from /_next/static/immutable/..., content-addressed by filename, cacheable indefinitely by the browser, and skippable during upload on subsequent deploys.

Code Examples

/** @type {import('next').NextConfig} */
const nextConfig = {
  supportsImmutableAssets: false,
}

module.exports = nextConfig

• O que demonstra: como um adapter/app desabilita o omitir do parâmetro ?dpl quando o provedor não suporta assets imutáveis.

Reference Tables

Version	Changes
v16.3.0	Added support for immutable static assets.

Anti-patterns

• Habilitar sem suporte do adapter: pode resultar em deployments quebrados; a opção só deve ser tocada ao debugar problemas específicos de adapter.

Key Takeaways

1. Opção de baixo nível, não é para app developers em uso normal, apenas troubleshooting.
2. Default assume que o adapter oferece suporte; setar false desativa o skip do ?dpl.
3. Assets imutáveis vivem em /_next/static/immutable/, diferente do path padrão /_next/static/.

Connects To

• adapters/immutable-static-assets: guia completo de como um adapter implementa suporte a esse recurso.