[a-hariti]

fixes #17367

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

[vercel]

@a-hariti is attempting to deploy a commit to the Sentry Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

Please update the IS YOUR CHANGE URGENT? section of the PR description:

• Select exactly one option.
• If you selected an urgent or other deadline, provide the date as YYYY-MM-DD.

This information helps the Docs team prioritize your review.

[cursor]

The plan checks image transfer size, LCP, CLS, and client errors. An issue escalates when CLS rises, LCP rises, or client errors rise. Wide images should transfer fewer bytes after deploy.

Services: sentry-docs, develop-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

Local markdown images wider than 900 pixels now encode width 900 and a scaled height. next/image builds srcset from that hash so wide images request smaller files. sentry-docs and develop-docs must deploy before this change is live. Both sites share this plugin under src.

Risk

A wrong scaled height may raise CLS on pages with a wide image. Invalid dimensions may cause next/image to fail and hide the figure. Both sites ship the same plugin so an error reaches both.

Intended effect

Wide images should transfer fewer bytes. Absent looks like p99 image transfer size holding near 85 KB. Pages can still load while that size does not fall.

Signal	Baseline	Rule	Source
p99 image transfer size	85 KB	fall below 85 KB	Sentry sentry/docs, span.op:resource.img environment:production, p99 http.response_transfer_size, 55397 spans, 2026-10-24T09:52:55Z to 2026-10-25T09:52:55Z. Fixes issues/17367

Fleet p95 stayed at 5 KB in the 24h and 48h windows. That value will not show this change. Use p99.

Regression watch

A wrong height shows as higher CLS. A next/image failure shows as more client errors. A bad srcset may also raise LCP.

Traces sample 30 percent of pageloads. Client errors are not sampled the same way. Compare the ratio to this band. Do not treat it as a user percent.

Signal	Baseline	Rule	Source
docs CLS p75	0.0066-0.0083	hold in band. Rise above 0.0083 is a regression	Sentry sentry/docs metrics, p75(value, browser.web_vital.cls), environment:production. 24h window 2026-10-24T09:52:55Z to 2026-10-25T09:52:55Z = 0.00834. 48h window 2026-10-23T09:52:55Z to 2026-10-25T09:52:55Z = 0.00663
docs LCP p75	1018-1200ms	hold in band. Rise above 1200ms is a regression	Sentry sentry/docs metrics, p75(value, browser.web_vital.lcp), environment:production. 24h = 1200ms. 48h pooled = 1018ms. Same windows as CLS
docs client errors per sampled pageload	0.078-0.208	hold in band. Rise above 0.208 is a regression	Sentry sentry/docs. Errors environment:production count() 24h = 896, prior 24h = 531. Pageload spans span.op:pageload environment:production 24h = 4313, prior 24h = 6814. Prior 24h is 2026-10-23T09:52:55Z to 2026-10-24T09:52:55Z
develop-docs CLS p75	0	hold at 0	Sentry sentry/develop-docs metrics, p75(value, browser.web_vital.cls), environment:production. 24h and 48h both 0. Same windows as docs
develop-docs LCP p75	1097-1164ms	hold in band. Rise above 1164ms is a regression	Sentry sentry/develop-docs metrics, p75(value, browser.web_vital.lcp), environment:production. 24h = 1164ms. 48h pooled = 1097ms

If CLS rises, inspect wide figures for a bad aspect ratio. If client errors rise, inspect next/image failures on DocImage.

Not observable

Sentry does not split image spans by intrinsic width. The pre-ship byte rate for images wider than 900 pixels is unknown. Fleet p50 image size is 814 bytes and p75 is 1164-1173 bytes. Those values will not show this change. Prior-day p99 image transfer size was not measured. Prior-day client errors for develop-docs were not measured. Image blur from upscaling has no signal.

[a-hariti]

@sergical Please allow deployment and take a look 👀

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 26, 2026 9:24pm UTC
sentry-docs	Error		Oct 26, 2026 9:24pm UTC

[sergical]

Checked the preview: no visible change, here or on prod. esbuild's file loader drops ?v=…#WxH from image imports, so DocImage never gets a size and renders a plain <img> instead of next/image. Confirmed locally on this branch.

Pushed a fix (234c36b): a small remark step after remark-mdx-images that adds #WxH back onto the src. With it, login-button.png (1600px) renders at 900px through next/image and goes from 315 KB PNG to 25 KB WebP.

[vercel]

Deployment failed for project develop-docs with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

[vercel]

Deployment failed for project sentry-docs with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

[sergical]

Reverted my fix (4b47abe). Routing images through next/image works, but has side effects:

• On 2x screens, screenshots render at ~800px instead of ~1000px, and the lightbox drops from ~1300px to 800px.
• Next 15 caches optimized images for 60s by default (our /mdx-images are max-age=0), so Vercel re-transforms and re-bills often.

Options:

1. Re-apply 234c36b plus: minimumCacheTTL: 2678400, the original file in the lightbox, and a fixed display width.
2. Compress the source PNGs once (e.g. oxipng/pngquant) and skip next/image. No runtime cost and no layout change.
3. Close this PR. The cap has no effect without one of the above.

@a-hariti which way do you want to go?

[a-hariti]

where is this configured?

our /mdx-images are max-age=0

the options

1. we can probably continue with routing trough next/image and a minimumCacheTTL
2. I think it will be a lot of work, probably slowing down build times
3. well ..., I think we should optimize images

[sergical]

@a-hariti https://nextjs.org/docs/app/api-reference/file-conventions/public-folder#caching its the default for public images

up to you!

[a-hariti]

I think next/image with a 1 day TTL sounds sensible, we could adjust based on bills

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 2474c23. Configure here.}

[a-hariti]

Please authorize the deployment @sergical