Add CSS URL deployment ID suffix support by sokra · Pull Request #89771 · vercel/next.js

sokra · 2026-02-10T15:59:26Z

Summary

Adds deployment ID suffix (?dpl=<deployment_id>) to asset URLs referenced in CSS url() declarations (images, fonts) for both Turbopack and Webpack builds. This enables proper cache busting for CSS-referenced assets when using deploymentId in next.config.js.

Turbopack

Added static_suffix field to the existing UrlBehavior struct, providing a build-time constant suffix for contexts that cannot use dynamic JS expressions (e.g., CSS url() references)
CSS URL resolution now calls url_behavior(None) and uses static_suffix instead of a separate method
Wired the suffix from next.config.js deploymentId through asset_suffix_path() into all three chunking contexts (client, server, edge) via default_url_behavior and url_behavior_override

Webpack

Passed deploymentId through the CSS loader config pipeline (webpack-config.ts → config/index.ts → css/loaders/ → postcss-url-parser.ts)
Appended ?dpl=<id> to resolved asset URLs in the PostCSS URL parser plugin, placed before any hash fragment so it remains a server-visible query parameter

Test

Added production test (test/production/css-url-deployment-id/) covering global CSS, CSS modules, and SCSS modules with image and font url() references
Verifies all asset URLs contain the dpl query parameter in both Turbopack and Webpack modes

nextjs-bot · 2026-02-10T16:06:05Z

Tests Passed

packages/next/src/build/webpack/loaders/css-loader/src/plugins/postcss-url-parser.ts

codspeed-hq · 2026-02-10T16:19:33Z

Merging this PR will not alter performance

✅ 17 untouched benchmarks
⏩ 3 skipped benchmarks¹

_{Comparing claude/turbopack-css-chunk-suffix-B02qw (e6fa053) with canary (ae64f6c)}

3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

nextjs-bot · 2026-02-10T16:22:22Z

Stats from current PR

✅ No significant changes detected

📊 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	456ms	✓	▁█▁▁▁
Cold (Ready in log)	435ms	435ms	✓	▅█▅▆▅
Cold (First Request)	1.156s	1.171s	✓	█▇███
Warm (Listen)	456ms	456ms	✓	▁█▁▁▁
Warm (Ready in log)	437ms	440ms	✓	▁█▁▁▁
Warm (First Request)	324ms	329ms	✓	▂█▁▄▂

📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric	Canary	PR	Change	Trend
Cold (Listen)	456ms	455ms	✓	▁▁▁█▁
Cold (Ready in log)	440ms	439ms	✓	▃▃▂▇▁
Cold (First Request)	1.851s	1.869s	✓	▂▁▁█▁
Warm (Listen)	456ms	456ms	✓	▁▁▁█▁
Warm (Ready in log)	439ms	439ms	✓	▂▂▂█▁
Warm (First Request)	1.850s	1.860s	✓	▂▁▁█▁

⚡ Production Builds

Metric	Canary	PR	Change	Trend
Fresh Build	3.782s	3.795s	✓	▁█▁▁▁
Cached Build	3.871s	3.842s	✓	▁█▁▁▁

📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric	Canary	PR	Change	Trend
Fresh Build	13.886s	13.912s	✓	▁▁▁▇▁
Cached Build	14.000s	13.990s	✓	▁▁▁▇▁
node_modules Size	467 MB	467 MB	✓	▁▁▁▁▁

📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **437 kB** → **437 kB** ⚠️ +10 B

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

Server

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	758 B	756 B	✓
Total	758 B	756 B	✅ -2 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	451 B	449 B	✓
Total	451 B	449 B	✅ -2 B

📦 Webpack

Client

Main Bundles

	Canary	PR	Change
5528-HASH.js gzip	5.47 kB	N/A	-
6280-HASH.js gzip	57 kB	N/A	-
6335.HASH.js gzip	169 B	N/A	-
912-HASH.js gzip	4.53 kB	N/A	-
e8aec2e4-HASH.js gzip	62.5 kB	N/A	-
framework-HASH.js gzip	59.7 kB	59.7 kB	✓
main-app-HASH.js gzip	256 B	252 B	🟢 4 B (-2%)
main-HASH.js gzip	39.1 kB	39.1 kB	✓
webpack-HASH.js gzip	1.68 kB	1.68 kB	✓
262-HASH.js gzip	N/A	4.53 kB	-
2889.HASH.js gzip	N/A	169 B	-
5602-HASH.js gzip	N/A	5.49 kB	-
6948ada0-HASH.js gzip	N/A	62.5 kB	-
9544-HASH.js gzip	N/A	57.7 kB	-
Total	230 kB	231 kB	⚠️ +642 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	194 B	✓
_error-HASH.js gzip	183 B	180 B	🟢 3 B (-2%)
css-HASH.js gzip	331 B	330 B	✓
dynamic-HASH.js gzip	1.81 kB	1.81 kB	✓
edge-ssr-HASH.js gzip	256 B	256 B	✓
head-HASH.js gzip	351 B	352 B	✓
hooks-HASH.js gzip	384 B	383 B	✓
image-HASH.js gzip	580 B	581 B	✓
index-HASH.js gzip	260 B	260 B	✓
link-HASH.js gzip	2.49 kB	2.49 kB	✓
routerDirect..HASH.js gzip	320 B	319 B	✓
script-HASH.js gzip	386 B	386 B	✓
withRouter-HASH.js gzip	315 B	315 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Total	7.97 kB	7.97 kB	✅ -1 B

Server

Edge SSR

	Canary	PR	Change
edge-ssr.js gzip	126 kB	126 kB	✓
page.js gzip	249 kB	250 kB	✓
Total	375 kB	376 kB	⚠️ +442 B

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	612 B	616 B	✓
middleware-r..fest.js gzip	156 B	155 B	✓
middleware.js gzip	33.3 kB	33 kB	✓
edge-runtime..pack.js gzip	842 B	842 B	✓
Total	34.9 kB	34.6 kB	✅ -269 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	733 B	735 B	✓
Total	733 B	735 B	⚠️ +2 B

Build Cache

	Canary	PR	Change
0.pack gzip	3.84 MB	3.85 MB	🔴 +9.87 kB (+0%)
index.pack gzip	104 kB	104 kB	✓
index.pack.old gzip	103 kB	102 kB	✓
Total	4.04 MB	4.05 MB	⚠️ +9 kB

🔄 Shared (bundler-independent)

Runtimes

	Canary	PR	Change
app-page-exp...dev.js gzip	316 kB	316 kB	✓
app-page-exp..prod.js gzip	168 kB	168 kB	✓
app-page-tur...dev.js gzip	315 kB	315 kB	✓
app-page-tur..prod.js gzip	167 kB	167 kB	✓
app-page-tur...dev.js gzip	312 kB	312 kB	✓
app-page-tur..prod.js gzip	166 kB	166 kB	✓
app-page.run...dev.js gzip	312 kB	312 kB	✓
app-page.run..prod.js gzip	166 kB	166 kB	✓
app-route-ex...dev.js gzip	70.5 kB	70.5 kB	✓
app-route-ex..prod.js gzip	49 kB	49 kB	✓
app-route-tu...dev.js gzip	70.5 kB	70.5 kB	✓
app-route-tu..prod.js gzip	49 kB	49 kB	✓
app-route-tu...dev.js gzip	70.1 kB	70.1 kB	✓
app-route-tu..prod.js gzip	48.8 kB	48.8 kB	✓
app-route.ru...dev.js gzip	70.1 kB	70.1 kB	✓
app-route.ru..prod.js gzip	48.8 kB	48.8 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	43.2 kB	43.2 kB	✓
pages-api-tu..prod.js gzip	32.9 kB	32.9 kB	✓
pages-api.ru...dev.js gzip	43.2 kB	43.2 kB	✓
pages-api.ru..prod.js gzip	32.8 kB	32.8 kB	✓
pages-turbo....dev.js gzip	52.5 kB	52.5 kB	✓
pages-turbo...prod.js gzip	39.4 kB	39.4 kB	✓
pages.runtim...dev.js gzip	52.5 kB	52.5 kB	✓
pages.runtim..prod.js gzip	39.4 kB	39.4 kB	✓
server.runti..prod.js gzip	62.7 kB	62.7 kB	✓
Total	2.8 MB	2.8 MB	⚠️ +2 B

sokra · 2026-02-10T21:41:30Z

Add CSS URL deployment ID suffix support #89771 👈 (View in Graphite)
canary

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

turbopack/crates/turbopack-browser/src/chunking_context.rs

…pack CSS `url()` references for images and fonts now include the `?dpl=<deployment_id>` suffix for skew protection. This applies to CSS modules, global CSS, and SCSS in both Turbopack and Webpack bundlers. Turbopack: Added `css_url_suffix` method to ChunkingContext trait, implemented in BrowserChunkingContext and NodeJsChunkingContext, and applied in resolve_url_reference. Webpack: Threaded deploymentId through the CSS loader pipeline from webpack-config through to postcss-url-parser where it's appended to asset URL hashes. https://claude.ai/code/session_01DE5Q9pRLpzjwbh7EnPiBTF

Place the dpl query parameter before the hash fragment in CSS url() references so it's a server-visible query parameter. Add missing sass dependency to the css-url-deployment-id test fixture.

Replace the separate `css_url_suffix` method on the ChunkingContext trait with a `static_suffix` field on the existing `UrlBehavior` struct. This unifies the dynamic (JS runtime) and static (CSS build-time) URL suffix mechanisms into a single configuration point, as suggested in code review. CSS URL resolution now calls `url_behavior(None)` and uses `static_suffix` instead of the removed `css_url_suffix()` method.

Fixes deployment test failure from #89771 x-ref: https://github.com/vercel/next.js/actions/runs/21921362927/job/63302154502 ## Summary - update the SCSS `url-global` background-image assertion to allow optional query suffixes on emitted svg asset URLs - this handles deploy-mode URLs that include `?dpl=...` while keeping the existing path checks intact ## Verification - validated against deploy logs from failing job `63302154502`: URLs are correct and include `?dpl=...` - local run: `NEXT_SKIP_ISOLATE=1 NEXT_TEST_MODE=dev pnpm testonly test/e2e/app-dir/scss/url-global/url-global.test.ts` - `sass` case passed - `sass-embedded` case blocked locally by missing `sass-embedded` module in this environment

nextjs-bot · 2026-02-12T06:00:31Z

Allow CI Workflow Run

approve CI run for commit: e6fa053

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

nextjs-bot · 2026-02-12T06:00:31Z

Allow CI Workflow Run

approve CI run for commit: e6fa053

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

This caused two requests and the preloading to not be effective at all #89771 added the dpl id in CSS for `url()`s

nextjs-bot added created-by: Turbopack team PRs by the Turbopack team. Font (next/font) Related to Next.js Font Optimization. tests Turbopack Related to Turbopack with Next.js. type: next labels Feb 10, 2026

vercel bot reviewed Feb 10, 2026

View reviewed changes

packages/next/src/build/webpack/loaders/css-loader/src/plugins/postcss-url-parser.ts Outdated Show resolved Hide resolved

sokra force-pushed the claude/turbopack-css-chunk-suffix-B02qw branch from 5cba3cc to 723b09f Compare February 10, 2026 21:41

sokra marked this pull request as ready for review February 10, 2026 23:32

sokra requested a review from mischnic February 10, 2026 23:32

mischnic reviewed Feb 11, 2026

View reviewed changes

turbopack/crates/turbopack-browser/src/chunking_context.rs Outdated Show resolved Hide resolved

claude and others added 3 commits February 11, 2026 14:36

Fix CSS url() deployment ID placement and test dependencies

5177c98

Place the dpl query parameter before the hash fragment in CSS url() references so it's a server-visible query parameter. Add missing sass dependency to the css-url-deployment-id test fixture.

sokra force-pushed the claude/turbopack-css-chunk-suffix-B02qw branch from 723b09f to e6fa053 Compare February 11, 2026 13:36

sokra requested a review from mischnic February 11, 2026 13:37

mischnic approved these changes Feb 11, 2026

View reviewed changes

sokra merged commit 24c6e3e into canary Feb 11, 2026
165 checks passed

sokra deleted the claude/turbopack-css-chunk-suffix-B02qw branch February 11, 2026 14:35

ijjk mentioned this pull request Feb 11, 2026

test: allow dpl query suffix in scss url-global expectation #89856

Merged

claude bot added the claude-code-assisted label Feb 12, 2026

mischnic mentioned this pull request Feb 13, 2026

Append deployment id query string for next-font #89960

Merged

mischnic added a commit that referenced this pull request Feb 13, 2026

Include deployment id query string for preloaded fonts (#89960)

7784b11

This caused two requests and the preloading to not be effective at all #89771 added the dpl id in CSS for `url()`s

github-actions bot added the locked label Feb 26, 2026

github-actions bot locked as resolved and limited conversation to collaborators Feb 26, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add CSS URL deployment ID suffix support#89771

Add CSS URL deployment ID suffix support#89771
sokra merged 3 commits intocanaryfrom
claude/turbopack-css-chunk-suffix-B02qw

sokra commented Feb 10, 2026 •

edited

Loading

Uh oh!

nextjs-bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

codspeed-hq bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

nextjs-bot commented Feb 10, 2026 •

edited

Loading

⚡ Dev Server

📦 Dev Server (Webpack)

⚡ Production Builds

📦 Production Builds (Webpack)

Bundle Sizes

⚡ Turbopack

📦 Webpack

🔄 Shared (bundler-independent)

Uh oh!

sokra commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

nextjs-bot commented Feb 12, 2026

Uh oh!

nextjs-bot commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

sokra commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Turbopack

Webpack

Test

Uh oh!

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

Uh oh!

Tests Passed

Uh oh!

Uh oh!

codspeed-hq bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

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

Uh oh!

Stats from current PR

✅ No significant changes detected

⚡ Dev Server

📦 Dev Server (Webpack)

⚡ Production Builds

📦 Production Builds (Webpack)

Bundle Sizes

⚡ Turbopack

📦 Webpack

🔄 Shared (bundler-independent)

Uh oh!

sokra commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

nextjs-bot commented Feb 12, 2026

Uh oh!

nextjs-bot commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sokra commented Feb 10, 2026 •

edited

Loading

nextjs-bot commented Feb 10, 2026 •

edited

Loading

codspeed-hq bot commented Feb 10, 2026 •

edited

Loading

nextjs-bot commented Feb 10, 2026 •

edited

Loading