feat: on-demand image optimization with sharp by rsbh · Pull Request #95 · raystack/chronicle

rsbh · 2026-05-20T10:06:15Z

Summary

Add /api/image endpoint that resizes + converts content images to WebP via sharp on first request
Remark plugin rewrites all image URLs (markdown, HTML, JSX) to route through the optimization endpoint
SSR preload links and client-side prefetch use optimized URLs
1.8MB PNG → 6KB WebP at 640w quality 75

Changes

src/server/api/image.ts — new optimization endpoint with disk caching, allowlisted widths, SVG passthrough
src/lib/image-utils.ts — shared helpers (buildOptimizedUrl, isLocalImage, isSvg)
src/lib/remark-resolve-images.ts — rewrite resolved image URLs through /api/image
src/components/mdx/image.tsx — route local images through optimization endpoint
src/server/vite-config.ts — externalize sharp for Nitro bundling
src/server/entry-server.tsx — preload optimized URLs, deduplicate
src/lib/page-context.tsx — client preload uses optimized URLs

Test plan

/api/image?url=/_content/...&w=640&q=75 returns 200 with WebP
SVG URLs return 307 redirect to original
Missing/invalid params return 400
SSR preload links point to optimized URLs
Build and tests pass

🤖 Generated with Claude Code

Add /api/image endpoint that resizes and converts content images to WebP on first request, caching results to disk. Images go from ~1.8MB originals to ~6KB optimized WebP at 640w. - New /api/image endpoint: accepts url, w (width), q (quality) params - Remark plugin rewrites image URLs to point through optimization endpoint - Image component and SSR preload use optimized URLs - SVGs pass through unchanged, sharp externalized for Nitro bundling - Allowlisted widths prevent cache flooding Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel · 2026-05-20T10:06:20Z

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

Project	Deployment	Actions	Updated (UTC)
chronicle	Ready	Preview, Comment	May 21, 2026 8:28am

coderabbitai · 2026-05-20T10:06:23Z

Warning

Rate limit exceeded

@rsbh has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 48 minutes and 18 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 31a19394-2b35-45dd-b6c5-765e348000ff

📥 Commits

Reviewing files that changed from the base of the PR and between 9acd409 and 647b564.

⛔ Files ignored due to path filters (1)

bun.lock is excluded by !**/*.lock

📒 Files selected for processing (11)

packages/chronicle/package.json
packages/chronicle/src/components/mdx/image.tsx
packages/chronicle/src/components/mdx/index.tsx
packages/chronicle/src/lib/image-utils.test.ts
packages/chronicle/src/lib/image-utils.ts
packages/chronicle/src/lib/page-context.tsx
packages/chronicle/src/lib/remark-resolve-images.ts
packages/chronicle/src/server/api/image.test.ts
packages/chronicle/src/server/api/image.ts
packages/chronicle/src/server/entry-server.tsx
packages/chronicle/src/server/vite-config.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/image-optimization

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Serve AVIF, WebP, or original format based on browser Accept header. AVIF preferred > WebP > original (resized only). Adds Vary: Accept for proper CDN caching. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Portable across deployment targets (filesystem, KV, Redis, etc.). Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Persists optimized images to .cache/images/ on disk. Survives server restarts. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Move useStorage before early returns to satisfy Biome hook ordering rule. Replace magic status numbers with StatusCodes constants. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Replace magic numbers 1024 and 75 with named constants from image-utils.ts, used across all image optimization call sites. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

24 tests covering negotiateFormat, cacheKey, MIME mapping, isLocalImage, isSvg, buildOptimizedUrl, and constants. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

rohanchkrabrty

.cache/images/ has no size cap or eviction — disk usage grows forever as content changes.
q accepts any 1–100; restrict to a few steps like [60, 75, 90], otherwise each image can produce 2,100 cache entries (100 × 3 formats × 7
widths).
Cache stampede in image.ts:86-99 — two concurrent requests for the same uncached variant both run sharp. Coalesce in-flight work with a
Map<key, Promise>.
cacheKey in image.ts:29-32 ignores mtime, so replacing an image at the same path keeps serving the old bytes. Mix fs.stat(filePath).mtimeMs
into the hash.
The remark plugin rewrites every to /api/image?…, so builds deployed to S3, Cloudflare Pages static, or GitHub Pages 404 on images.
Either pre-generate variants at build time, or skip the rewrite when the preset has no Node runtime.

- Restrict quality to allowed steps [60, 75, 90, 100] with snap-to-nearest - Add cache stampede protection via in-flight promise map - Add LRU cache eviction with 500 entry cap - Skip image optimization rewrite for static build presets - Accept optimize option in remark-resolve-images plugin Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

rsbh · 2026-05-21T09:42:20Z

Review fixes applied

Quality restricted to allowed steps [60, 75, 90, 100] with snap-to-nearest (was any 1-100)
Cache stampede protection via in-flight promise map — concurrent requests for same variant coalesce
Cache eviction with 500 entry cap (oldest entries removed on insert)
Remark plugin accepts optimize option — disabled for static build presets (vercel-static, cloudflare-pages, github-pages) so images don't 404
Removed mtime from cache key — cache is ephemeral (pod resets on deploy)

vercel Bot deployed to Preview May 20, 2026 10:06 View deployment

rsbh marked this pull request as draft May 20, 2026 10:48

fix: remove unnecessary window.Image, use Image directly

33718c0

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 20, 2026 10:53 View deployment

refactor: rename Image component to MDXImage

de8461c

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 03:48 View deployment

refactor: use top-level import for sharp

89d104e

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 03:49 View deployment

feat: content negotiation via Accept header for image format

2e10457

Serve AVIF, WebP, or original format based on browser Accept header. AVIF preferred > WebP > original (resized only). Adds Vary: Accept for proper CDN caching. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 03:56 View deployment

refactor: use Nitro storage for image cache instead of manual fs

a71d662

Portable across deployment targets (filesystem, KV, Redis, etc.). Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 03:58 View deployment

refactor: extract image-cache storage key to constant

8a82169

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 04:00 View deployment

feat: configure fs storage driver for image cache

5506438

Persists optimized images to .cache/images/ on disk. Survives server restarts. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 04:03 View deployment

rsbh marked this pull request as ready for review May 21, 2026 04:04

rsbh and others added 2 commits May 21, 2026 09:36

fix: use StatusCodes from http-status-codes, fix lint error

5353aae

Move useStorage before early returns to satisfy Biome hook ordering rule. Replace magic status numbers with StatusCodes constants. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

style: restore semicolons in new files

ea99550

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 04:08 View deployment

refactor: extract DEFAULT_WIDTH and DEFAULT_QUALITY constants

69ef0b1

Replace magic numbers 1024 and 75 with named constants from image-utils.ts, used across all image optimization call sites. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 04:11 View deployment

test: add tests for image optimization utilities and API

9ecb353

24 tests covering negotiateFormat, cacheKey, MIME mapping, isLocalImage, isSvg, buildOptimizedUrl, and constants. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

vercel Bot deployed to Preview May 21, 2026 04:13 View deployment

rsbh requested a review from rohanchkrabrty May 21, 2026 06:58

rohanchkrabrty requested changes May 21, 2026

View reviewed changes

vercel Bot deployed to Preview May 21, 2026 08:28 View deployment

rohanchkrabrty approved these changes May 21, 2026

View reviewed changes

rsbh merged commit a38e999 into main May 21, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: on-demand image optimization with sharp#95

feat: on-demand image optimization with sharp#95
rsbh merged 13 commits into
mainfrom
feat/image-optimization

rsbh commented May 20, 2026

Uh oh!

vercel Bot commented May 20, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 20, 2026 •

edited

Loading

Rate limit exceeded

Uh oh!

rohanchkrabrty left a comment

Uh oh!

rsbh commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

rsbh commented May 20, 2026

Summary

Changes

Test plan

Uh oh!

vercel Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Uh oh!

rohanchkrabrty left a comment

Choose a reason for hiding this comment

Uh oh!

rsbh commented May 21, 2026

Review fixes applied

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented May 20, 2026 •

edited

Loading

coderabbitai Bot commented May 20, 2026 •

edited

Loading