next/image: support custom cache handlers #88248

ztanner · 2026-01-07T23:50:58Z

When self-hosting Next.js, it's possible to customize a cache handler for ISR. Self-hosted Next.js also makes use of a similar cache interface for next/image, but there's no way to customize this cache handler.

This plugs into the existing ability to customize a cacheHandler to support the IMAGE type. This lets you implement whatever constraints you might have on your self-hosted environment, eg the need for an LRU cache, or storing optimized images outside of disk.

This is currently opt-in because it's a breaking change for cache handlers to start receiving IMAGE cache types, which we'll make default in the next major.

ztanner · 2026-01-07T23:51:20Z

next/image: support custom cache handlers #88248 👈 (View in Graphite)
canary

This stack of pull requests is managed by Graphite. Learn more about stacking.

nextjs-bot · 2026-01-07T23:57:37Z

Tests Passed

packages/next/src/server/next-server.ts

nextjs-bot · 2026-01-08T00:27:41Z

Stats from current PR

🔴 1 regression

Metric	Canary	PR	Change	Trend
node_modules Size	458 MB	458 MB	🔴 +55 kB (+0%)	█████

📊 All Metrics

📖 Metrics Glossary

Dev Server Metrics:

Listen = TCP port starts accepting connections
First Request = HTTP server returns successful response
Cold = Fresh build (no cache)
Warm = With cached build artifacts

Build Metrics:

Fresh = Clean build (no .next directory)
Cached = With existing .next directory

Change Thresholds:

Time: Changes < 50ms AND < 10%, OR < 2% are insignificant
Size: Changes < 1KB AND < 1% are insignificant
All other changes are flagged to catch regressions

⚡ Dev Server

Metric	Canary	PR	Change	Trend
Cold (Listen)	455ms	455ms	✓	█▁▁▁▁
Cold (First Request)	1.122s	1.121s	✓	▂█▇▇█
Warm (Listen)	456ms	456ms	✓	██▁██
Warm (First Request)	334ms	334ms	✓	█▁▁▄▂

📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric	Canary	PR	Change	Trend
Cold (Listen)	456ms	456ms	✓	█▁▁▁▁
Cold (First Request)	1.810s	1.839s	✓	▆▆▆▁▇
Warm (Listen)	456ms	456ms	✓	▅▅▅▁▅
Warm (First Request)	1.841s	1.846s	✓	▇▆▅▁▆

⚡ Production Builds

Metric	Canary	PR	Change	Trend
Fresh Build	4.086s	4.059s	✓	█▁▁▁▃
Cached Build	4.115s	4.089s	✓	█▁▂▁▅

📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric	Canary	PR	Change	Trend
Fresh Build	14.001s	13.972s	✓	▂▂▁▁▂
Cached Build	14.051s	14.090s	✓	▃▂▁▁▃
node_modules Size	458 MB	458 MB	🔴 +55 kB (+0%)	█████

📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **431 kB** → **431 kB** ⚠️ +120 B

82 files with content-based hashes (individual files not comparable between builds)

Server

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	788 B	790 B	✓
Total	788 B	790 B	⚠️ +2 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	450 B	449 B	✓
Total	450 B	449 B	✅ -1 B

📦 Webpack

Client

Main Bundles

	Canary	PR	Change
2086.HASH.js gzip	169 B	N/A	-
2161-HASH.js gzip	5.4 kB	N/A	-
2747-HASH.js gzip	4.48 kB	N/A	-
4322-HASH.js gzip	52.7 kB	N/A	-
ec793fe8-HASH.js gzip	62.3 kB	N/A	-
framework-HASH.js gzip	59.8 kB	59.8 kB	✓
main-app-HASH.js gzip	251 B	254 B	🔴 +3 B (+1%)
main-HASH.js gzip	38.6 kB	39 kB	🔴 +392 B (+1%)
webpack-HASH.js gzip	1.68 kB	1.68 kB	✓
1596.HASH.js gzip	N/A	169 B	-
2658-HASH.js gzip	N/A	52.5 kB	-
6349-HASH.js gzip	N/A	4.46 kB	-
7019-HASH.js gzip	N/A	5.43 kB	-
b17a3386-HASH.js gzip	N/A	62.3 kB	-
Total	225 kB	225 kB	⚠️ +181 B

Polyfills

	Canary	PR	Change
polyfills-HASH.js gzip	39.4 kB	39.4 kB	✓
Total	39.4 kB	39.4 kB	✓

Pages

	Canary	PR	Change
_app-HASH.js gzip	194 B	193 B	✓
_error-HASH.js gzip	182 B	182 B	✓
css-HASH.js gzip	336 B	335 B	✓
dynamic-HASH.js gzip	1.8 kB	1.8 kB	✓
edge-ssr-HASH.js gzip	256 B	256 B	✓
head-HASH.js gzip	352 B	349 B	✓
hooks-HASH.js gzip	385 B	384 B	✓
image-HASH.js gzip	580 B	580 B	✓
index-HASH.js gzip	259 B	258 B	✓
link-HASH.js gzip	2.5 kB	2.51 kB	✓
routerDirect..HASH.js gzip	319 B	317 B	✓
script-HASH.js gzip	385 B	387 B	✓
withRouter-HASH.js gzip	316 B	315 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Total	7.97 kB	7.96 kB	✅ -8 B

Server

Edge SSR

	Canary	PR	Change
edge-ssr.js gzip	125 kB	125 kB	✓
page.js gzip	241 kB	241 kB	✓
Total	366 kB	366 kB	⚠️ +518 B

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	654 B	653 B	✓
middleware-r..fest.js gzip	155 B	156 B	✓
middleware.js gzip	33.3 kB	33.3 kB	✓
edge-runtime..pack.js gzip	842 B	842 B	✓
Total	34.9 kB	34.9 kB	⚠️ +32 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	738 B	738 B	✓
Total	738 B	738 B	✓

Build Cache

	Canary	PR	Change
0.pack gzip	3.63 MB	3.64 MB	🔴 +6.79 kB (+0%)
index.pack gzip	98.7 kB	100 kB	🔴 +1.73 kB (+2%)
index.pack.old gzip	100 kB	100 kB	✓
Total	3.83 MB	3.84 MB	⚠️ +8.35 kB

🔄 Shared (bundler-independent)

Runtimes

	Canary	PR	Change
app-page-exp...dev.js gzip	303 kB	303 kB	✓
app-page-exp..prod.js gzip	158 kB	158 kB	✓
app-page-tur...dev.js gzip	303 kB	303 kB	✓
app-page-tur..prod.js gzip	158 kB	158 kB	✓
app-page-tur...dev.js gzip	300 kB	300 kB	✓
app-page-tur..prod.js gzip	156 kB	156 kB	✓
app-page.run...dev.js gzip	300 kB	300 kB	✓
app-page.run..prod.js gzip	156 kB	156 kB	✓
app-route-ex...dev.js gzip	68.7 kB	68.7 kB	✓
app-route-ex..prod.js gzip	47.5 kB	47.5 kB	✓
app-route-tu...dev.js gzip	68.8 kB	68.8 kB	✓
app-route-tu..prod.js gzip	47.6 kB	47.6 kB	✓
app-route-tu...dev.js gzip	68.4 kB	68.4 kB	✓
app-route-tu..prod.js gzip	47.3 kB	47.3 kB	✓
app-route.ru...dev.js gzip	68.3 kB	68.3 kB	✓
app-route.ru..prod.js gzip	47.3 kB	47.3 kB	✓
dist_client_...dev.js gzip	324 B	324 B	✓
dist_client_...dev.js gzip	326 B	326 B	✓
dist_client_...dev.js gzip	318 B	318 B	✓
dist_client_...dev.js gzip	317 B	317 B	✓
pages-api-tu...dev.js gzip	41.1 kB	41.1 kB	✓
pages-api-tu..prod.js gzip	31.2 kB	31.2 kB	✓
pages-api.ru...dev.js gzip	41.1 kB	41.1 kB	✓
pages-api.ru..prod.js gzip	31.2 kB	31.2 kB	✓
pages-turbo....dev.js gzip	50.8 kB	50.8 kB	✓
pages-turbo...prod.js gzip	38.2 kB	38.2 kB	✓
pages.runtim...dev.js gzip	50.8 kB	50.8 kB	✓
pages.runtim..prod.js gzip	38.2 kB	38.2 kB	✓
server.runti..prod.js gzip	62.2 kB	62.2 kB	✓
Total	2.68 MB	2.68 MB	⚠️ +119 B

📝 Changed Files (13 files)

Files with changes:

app-page-exp..ntime.dev.js
app-page-exp..time.prod.js
app-page-tur..ntime.dev.js
app-page-tur..time.prod.js
app-page-tur..ntime.dev.js
app-page-tur..time.prod.js
app-page.runtime.dev.js
app-page.runtime.prod.js
pages-turbo...ntime.dev.js
pages-turbo...time.prod.js
pages.runtime.dev.js
pages.runtime.prod.js
server.runtime.prod.js

View diffs

app-page-exp..ntime.dev.js

Diff too large to display

app-page-exp..time.prod.js

Diff too large to display

app-page-tur..ntime.dev.js

Diff too large to display

app-page-tur..time.prod.js

Diff too large to display

app-page-tur..ntime.dev.js

Diff too large to display

app-page-tur..time.prod.js

Diff too large to display

app-page.runtime.dev.js

Diff too large to display

app-page.runtime.prod.js

Diff too large to display

pages-turbo...ntime.dev.js

Diff too large to display

pages-turbo...time.prod.js

Diff too large to display

pages.runtime.dev.js

Diff too large to display

pages.runtime.prod.js

Diff too large to display

server.runtime.prod.js

Diff too large to display

packages/next/src/server/image-optimizer.ts

packages/next/src/shared/lib/image-config.ts

packages/next/src/server/image-optimizer.ts

styfle

Thanks!

When self-hosting Next.js, it's possible to customize a cache handler for ISR. Self-hosted Next.js also makes use of a similar cache interface for `next/image`, but there's no way to customize this cache handler. This plugs into the [existing ability](https://nextjs.org/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath) to customize a `cacheHandler` to support the `IMAGE` type. This lets you implement whatever constraints you might have on your self-hosted environment, eg the need for an LRU cache, or storing optimized images outside of disk. This is currently opt-in because it's a breaking change for cache handlers to start receiving `IMAGE` cache types, which we'll make default in the next major.

nextjs-bot added created-by: Next.js team PRs by the Next.js team. tests type: next labels Jan 7, 2026

vercel bot reviewed Jan 8, 2026

View reviewed changes

packages/next/src/server/next-server.ts Outdated Show resolved Hide resolved

next/image: support custom cache handlers

77b477f

ztanner force-pushed the 01-07-next_image_support_custom_cache_handlers branch from 0a708dd to 77b477f Compare January 8, 2026 00:09

nextjs-bot added the Documentation Related to Next.js' official documentation. label Jan 8, 2026

ztanner force-pushed the 01-07-next_image_support_custom_cache_handlers branch from 24f03ce to e216e59 Compare January 8, 2026 16:51

add docs & put behind flag

5c9cd8e

ztanner force-pushed the 01-07-next_image_support_custom_cache_handlers branch from e216e59 to 5c9cd8e Compare January 8, 2026 17:23

ztanner marked this pull request as ready for review January 8, 2026 17:43

ztanner requested review from ijjk and styfle January 8, 2026 17:47

ijjk approved these changes Jan 8, 2026

View reviewed changes

styfle reviewed Jan 8, 2026

View reviewed changes

packages/next/src/server/image-optimizer.ts Show resolved Hide resolved

styfle reviewed Jan 8, 2026

View reviewed changes

packages/next/src/server/image-optimizer.ts Show resolved Hide resolved

styfle reviewed Jan 8, 2026

View reviewed changes

packages/next/src/shared/lib/image-config.ts Show resolved Hide resolved

styfle reviewed Jan 8, 2026

View reviewed changes

packages/next/src/server/image-optimizer.ts Outdated Show resolved Hide resolved

CR feedback

712064d

styfle approved these changes Jan 8, 2026

View reviewed changes

ztanner merged commit 0d46499 into canary Jan 8, 2026
291 of 297 checks passed

ztanner deleted the 01-07-next_image_support_custom_cache_handlers branch January 8, 2026 18:58

bestickley mentioned this pull request Jan 9, 2026

Use S3 For Cache Instead of EFS To Eliminate Default NAT Gateway? cdklabs/cdk-nextjs#127

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

next/image: support custom cache handlers #88248

next/image: support custom cache handlers #88248

Uh oh!

ztanner commented Jan 7, 2026 •

edited

Loading

Uh oh!

ztanner commented Jan 7, 2026

Uh oh!

nextjs-bot commented Jan 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

nextjs-bot commented Jan 8, 2026 •

edited

Loading

⚡ Dev Server

📦 Dev Server (Webpack)

⚡ Production Builds

📦 Production Builds (Webpack)

Bundle Sizes

⚡ Turbopack

📦 Webpack

🔄 Shared (bundler-independent)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

styfle left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

next/image: support custom cache handlers #88248

next/image: support custom cache handlers #88248

Uh oh!

Conversation

ztanner commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ztanner commented Jan 7, 2026

Uh oh!

nextjs-bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tests Passed

Uh oh!

Uh oh!

nextjs-bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Stats from current PR

🔴 1 regression

⚡ Dev Server

📦 Dev Server (Webpack)

⚡ Production Builds

📦 Production Builds (Webpack)

Bundle Sizes

⚡ Turbopack

📦 Webpack

🔄 Shared (bundler-independent)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

styfle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ztanner commented Jan 7, 2026 •

edited

Loading

nextjs-bot commented Jan 7, 2026 •

edited

Loading

nextjs-bot commented Jan 8, 2026 •

edited

Loading