Unverified Commit 3ebd45b1 authored by Niklas Mischkulnig's avatar Niklas Mischkulnig Committed by GitHub

docs: Immutable static assets (#95348)

<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:

## For Contributors

### Improving Documentation

- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide

### Fixing a bug

- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Adding a feature

- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Signed commits

- This repository requires verified commit signatures on protected
branches.
- If this pull request is blocked for unsigned commits, re-sign the
commits and force-push the branch.
- A `Signed-off-by` line in the commit message is not enough.


## For Maintainers

- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Closes NEXT-
Fixes #

-->
parent 359d6681
---
title: supportsImmutableAssets
description: Configure support for immutable static assets
---
> **Attention**: This option is primarily intended for [adapter](/docs/app/api-reference/adapters) authors.
> App developers should only set it when troubleshooting adapter-specific issues.
>
> **Enabling this feature when your provider or adapter does not support it can result in broken deployments.**
When skew protection is enabled, static asset requests include a deployment-specific query parameter, for example:
```plain
GET https://foo.com/_next/static/chunks/0d_ks0ow7ur6m.js?dpl=<unique-deployment-id>
```
One downside is that browsers have to download static assets again after each new deployment, even when those assets have not changed.
Immutable static assets allow the `?dpl` query parameter to be omitted for static assets that are guaranteed to be immutable and content-addressed by their filename. This lets browsers cache those assets indefinitely and allows unchanged static assets to be skipped when uploading files during subsequent deployments:
```plain
GET https://foo.com/_next/static/immutable/chunks/0d_ks0ow7ur6m.js
```
You can use this config option to opt out of immutable static assets when your adapter has enabled support for them. If your adapter has not enabled this feature, this option has no effect:
```js filename="next.config.js"
/** @type {import('next').NextConfig} */
const nextConfig = {
supportsImmutableAssets: false,
}
module.exports = nextConfig
```
See [Supporting immutable static assets](/docs/app/api-reference/adapters/immutable-static-assets) for more information on how to support this feature in an adapter.
## Version History
| Version | Changes |
| --------- | ------------------------------------------ |
| `v16.3.0` | Added support for immutable static assets. |
......@@ -173,6 +173,8 @@ Static assets and auto-statically optimized pages:
}
```
See [Supporting immutable static assets](/docs/app/api-reference/adapters/immutable-static-assets) for more information about `immutableHash`.
## Middleware (`outputs.middleware`)
`middleware.ts` (`.js`/`.ts`) or `proxy.ts` (`.js`/`.ts`) function (if present):
......
---
title: Supporting Immutable Static Assets
description: Support immutable static assets in an adapter
---
See [`config.supportsImmutableAssets`](/docs/app/api-reference/config/next-config-js/supportsImmutableAssets) for end-user-facing information about this feature.
When `config.supportsImmutableAssets` is enabled, Next.js outputs immutable content-addressed static assets under the public path `/_next/static/immutable/*`. This prefix can be used to differentiate immutable static assets from non-immutable static assets at the CDN level.
At runtime, these immutable static assets are requested without the `?dpl` query parameter and thus live in a shared namespace across deployments. You must ensure that these assets are immutable and will never be changed or deleted, even after a new deployment. Next.js may use a truncated shorter content hash as the filename, so `outputs.staticFiles[].immutableHash` contains the full content hash which can be used to validate that no hash collision occurred.
You can use `config.experimental.outputHashSalt` to set a salt for the content hashes, if you want to rotate the hashes for any reason (e.g. after a detected hash collision).
Note that you need to continue supporting non-immutable static assets (which may change between deployments and continue to be requested with the `?dpl` query parameter), e.g. for the `public` folder or for older Next.js versions.
## Adapter Implementation
You need to:
1. In the `modifyConfig`, set the `config.supportsImmutableAssets` property to `true` (if it's not already set to `false` by the user) to signal that you support deploying immutable static assets, and
2. In `onBuildComplete`, read the `outputs.staticFiles[].immutableHash` property to determine which static assets are immutable and have to be requested without the `?dpl` query parameter.
```js filename="my-adapter.js"
/** @type {import('next').NextAdapter} */
const adapter = {
name: 'my-custom-adapter',
async modifyConfig(config, { phase }) {
if (phase === 'phase-production-build') {
config.supportsImmutableAssets =
// Default to true, but allow users to opt-out
config.supportsImmutableAssets ?? true
// Optionally, pass a salt for the content hashes
// config.experimental.outputHashSalt = getSaltForCurrentProject()
}
return config
},
async onBuildComplete({ outputs }) {
for (const output of outputs.staticFiles) {
if (output.immutableHash != null) {
// This has to be requestable at `output.pathname`
// even without the `?dpl` query parameter.
uploadOrVerifyImmutableStaticAsset(
output.filePath,
output.pathname,
output.immutableHash
)
} else {
// This is a non-immutable static asset and will be requested with
// the `?dpl` query parameter, scoped to the deployment.
uploadStaticAsset(output.filePath, output.pathname)
}
}
// Process other outputs....
},
}
```
......@@ -16,3 +16,4 @@ Use this section to build and validate deployment adapters that integrate with t
- [Output Types](/docs/app/api-reference/adapters/output-types)
- [Routing Information](/docs/app/api-reference/adapters/routing-information)
- [Use Cases](/docs/app/api-reference/adapters/use-cases)
- [Supporting Immutable Static Assets](/docs/app/api-reference/adapters/immutable-static-assets)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment