feat: on-demand image optimization with sharp (#95)

* feat: on-demand image optimization with sharp

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) <noreply@anthropic.com>

* fix: remove unnecessary window.Image, use Image directly

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: rename Image component to MDXImage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: use top-level import for sharp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: content negotiation via Accept header for image format

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) <noreply@anthropic.com>

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

Portable across deployment targets (filesystem, KV, Redis, etc.).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: extract image-cache storage key to constant

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: configure fs storage driver for image cache

Persists optimized images to .cache/images/ on disk. Survives
server restarts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

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) <noreply@anthropic.com>

* style: restore semicolons in new files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: extract DEFAULT_WIDTH and DEFAULT_QUALITY constants

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) <noreply@anthropic.com>

* test: add tests for image optimization utilities and API

24 tests covering negotiateFormat, cacheKey, MIME mapping,
isLocalImage, isSvg, buildOptimizedUrl, and constants.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address image optimization review comments

- 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) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rsbh

bun.lock

@@ -77,6 +77,7 @@
     "remark-mdx-frontmatter": "^5.2.0",
     "remark-parse": "^11.0.0",
     "satori": "^0.25.0",
+    "sharp": "^0.34.5",
     "slugify": "^1.6.6",
     "std-env": "^4.1.0",
     "unified": "^11.0.5",

packages/chronicle/package.json

@@ -1,9 +1,13 @@
 import type { ComponentProps } from 'react';
+import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from '@/lib/image-utils';
 
-type ImageProps = ComponentProps<'img'>;
+type MDXImageProps = ComponentProps<'img'>;
 
-export function Image({ src, alt, ...props }: ImageProps) {
+export function MDXImage({ src, alt, ...props }: MDXImageProps) {
   if (!src) return null;
 
-  return <img src={src} alt={alt ?? ''} loading='lazy' {...props} />;
+  const optimize = isLocalImage(src) && !isSvg(src);
+  const imgSrc = optimize ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
+
+  return <img src={imgSrc} alt={alt ?? ''} loading='lazy' decoding='async' {...props} />;
 }

packages/chronicle/src/components/mdx/image.tsx

@@ -1,5 +1,5 @@
 import type { MDXComponents } from 'mdx/types'
-import { Image } from './image'
+import { MDXImage } from './image'
 import { Link } from './link'
 import { MdxTable, MdxThead, MdxTbody, MdxTr, MdxTh, MdxTd } from './table'
 import { MdxPre, MdxCode } from './code'
@@ -25,7 +25,7 @@ MdxTabs.Content = Tabs.Content
 
 export const mdxComponents: MDXComponents = {
   p: MdxParagraph,
-  img: Image,
+  img: MDXImage,
   a: Link,
   table: MdxTable,
   thead: MdxThead,
@@ -45,5 +45,5 @@ export const mdxComponents: MDXComponents = {
   Mermaid,
 }
 
-export { Image } from './image'
+export { MDXImage } from './image'
 export { Link } from './link'

packages/chronicle/src/components/mdx/index.tsx

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  isLocalImage,
+  isSvg,
+  buildOptimizedUrl,
+  ALLOWED_WIDTHS,
+  DEFAULT_WIDTH,
+  DEFAULT_QUALITY,
+} from './image-utils';
+
+describe('isLocalImage', () => {
+  test('returns true for /_content/ URLs', () => {
+    expect(isLocalImage('/_content/docs/photo.png')).toBe(true);
+  });
+
+  test('returns false for external URLs', () => {
+    expect(isLocalImage('https://example.com/img.png')).toBe(false);
+  });
+
+  test('returns false for relative URLs', () => {
+    expect(isLocalImage('/images/logo.png')).toBe(false);
+  });
+});
+
+describe('isSvg', () => {
+  test('returns true for .svg files', () => {
+    expect(isSvg('/_content/logo.svg')).toBe(true);
+  });
+
+  test('returns true for .svg with query string', () => {
+    expect(isSvg('/_content/logo.svg?v=1')).toBe(true);
+  });
+
+  test('returns false for .png files', () => {
+    expect(isSvg('/_content/photo.png')).toBe(false);
+  });
+});
+
+describe('buildOptimizedUrl', () => {
+  test('builds URL with width and default quality', () => {
+    const url = buildOptimizedUrl('/_content/img.png', 640);
+    expect(url).toBe(`/api/image?url=%2F_content%2Fimg.png&w=640&q=${DEFAULT_QUALITY}`);
+  });
+
+  test('builds URL with custom quality', () => {
+    const url = buildOptimizedUrl('/_content/img.png', 320, 50);
+    expect(url).toBe('/api/image?url=%2F_content%2Fimg.png&w=320&q=50');
+  });
+
+  test('encodes special characters in URL', () => {
+    const url = buildOptimizedUrl('/_content/my image (1).png', 640);
+    expect(url).toContain('my%20image%20(1).png');
+  });
+});
+
+describe('constants', () => {
+  test('ALLOWED_WIDTHS is sorted ascending', () => {
+    for (let i = 1; i < ALLOWED_WIDTHS.length; i++) {
+      expect(ALLOWED_WIDTHS[i]).toBeGreaterThan(ALLOWED_WIDTHS[i - 1]);
+    }
+  });
+
+  test('DEFAULT_WIDTH is in ALLOWED_WIDTHS', () => {
+    expect(ALLOWED_WIDTHS).toContain(DEFAULT_WIDTH);
+  });
+
+  test('DEFAULT_QUALITY is between 1 and 100', () => {
+    expect(DEFAULT_QUALITY).toBeGreaterThanOrEqual(1);
+    expect(DEFAULT_QUALITY).toBeLessThanOrEqual(100);
+  });
+});

packages/chronicle/src/lib/image-utils.test.ts

@@ -0,0 +1,18 @@
+const ALLOWED_WIDTHS = [320, 640, 768, 1024, 1280, 1536, 1920];
+const ALLOWED_QUALITIES = [60, 75, 90, 100];
+const DEFAULT_WIDTH = 1024;
+const DEFAULT_QUALITY = 75;
+
+export function isLocalImage(url: string): boolean {
+  return url.startsWith('/_content/');
+}
+
+export function isSvg(url: string): boolean {
+  return url.split('?')[0].endsWith('.svg');
+}
+
+export function buildOptimizedUrl(url: string, width: number, quality = DEFAULT_QUALITY): string {
+  return `/api/image?url=${encodeURIComponent(url)}&w=${width}&q=${quality}`;
+}
+
+export { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_WIDTH, DEFAULT_QUALITY };

packages/chronicle/src/lib/image-utils.ts

@@ -14,6 +14,7 @@ import type { VersionContext } from '@/lib/version-source';
 import { LATEST_CONTEXT } from '@/lib/version-source';
 import type { ChronicleConfig, Frontmatter, Page, PageNavLink, Root, TableOfContents } from '@/types';
 import { queryClient } from '@/lib/preload';
+import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from '@/lib/image-utils';
 
 export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
@@ -136,7 +137,7 @@ export function PageProvider({
       if (data.images?.length) {
         for (const src of data.images) {
           const img = new Image();
-          img.src = src;
+          img.src = isLocalImage(src) && !isSvg(src) ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
         }
       }
       const { content, toc } = await loadMdx(data.originalPath || data.relativePath);

packages/chronicle/src/lib/page-context.tsx

@@ -5,6 +5,7 @@ import type { Image, Html } from 'mdast'
 import type { Element } from 'hast'
 import type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute } from 'mdast-util-mdx-jsx'
 import { MdxNodeType } from './mdx-utils'
+import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from './image-utils'
 
 function resolveUrl(src: string, dir: string): string {
   if (/^[a-z][a-z0-9+\-.]*:/i.test(src)) return src
@@ -16,7 +17,17 @@ function resolveUrl(src: string, dir: string): string {
   return `/_content/${path.posix.normalize(path.posix.join(dir, src))}`
 }
 
-const remarkResolveImages: Plugin = () => {
+interface RemarkResolveImagesOptions {
+  optimize?: boolean
+}
+
+function optimizeUrl(url: string, optimize: boolean): string {
+  if (optimize && isLocalImage(url) && !isSvg(url)) return buildOptimizedUrl(url, DEFAULT_WIDTH)
+  return url
+}
+
+const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) => {
+  const optimize = options?.optimize ?? true
   return (tree, file) => {
     const filePath = file.path
     if (!filePath) return
@@ -40,6 +51,7 @@ const remarkResolveImages: Plugin = () => {
       if (!node.url) return
       node.url = resolveUrl(node.url, dir)
       collect(node.url)
+      node.url = optimizeUrl(node.url, optimize)
     })
 
     visit(tree, 'html', (node: Html) => {
@@ -48,7 +60,7 @@ const remarkResolveImages: Plugin = () => {
         (_, before, src, after) => {
           const resolved = resolveUrl(src, dir)
           collect(resolved)
-          return `${before}${resolved}${after}`
+          return `${before}${optimizeUrl(resolved, optimize)}${after}`
         }
       )
     })
@@ -61,6 +73,7 @@ const remarkResolveImages: Plugin = () => {
       if (!srcAttr?.value || typeof srcAttr.value !== 'string') return
       srcAttr.value = resolveUrl(srcAttr.value, dir)
       collect(srcAttr.value)
+      srcAttr.value = optimizeUrl(srcAttr.value, optimize)
     })
 
     visit(tree, 'element', (node: Element) => {
@@ -69,6 +82,7 @@ const remarkResolveImages: Plugin = () => {
       if (typeof src !== 'string') return
       node.properties.src = resolveUrl(src, dir)
       collect(node.properties.src as string)
+      node.properties.src = optimizeUrl(node.properties.src as string, optimize)
     })
 
     file.data.images = images

packages/chronicle/src/lib/remark-resolve-images.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'bun:test';
+import { negotiateFormat, cacheKey, MIME } from './image';
+
+describe('negotiateFormat', () => {
+  test('returns avif when Accept includes image/avif', () => {
+    expect(negotiateFormat('image/avif,image/webp,*/*')).toBe('avif');
+  });
+
+  test('returns webp when Accept includes image/webp but not avif', () => {
+    expect(negotiateFormat('image/webp,image/png,*/*')).toBe('webp');
+  });
+
+  test('returns original when Accept has neither avif nor webp', () => {
+    expect(negotiateFormat('image/png,*/*')).toBe('original');
+  });
+
+  test('returns original for null Accept header', () => {
+    expect(negotiateFormat(null)).toBe('original');
+  });
+
+  test('prefers avif over webp when both present', () => {
+    expect(negotiateFormat('image/webp,image/avif')).toBe('avif');
+  });
+});
+
+describe('cacheKey', () => {
+  test('returns deterministic key for same inputs', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 640, 75, 'webp');
+    expect(a).toBe(b);
+  });
+
+  test('returns different keys for different widths', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 1024, 75, 'webp');
+    expect(a).not.toBe(b);
+  });
+
+  test('returns different keys for different formats', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 640, 75, 'avif');
+    expect(a).not.toBe(b);
+  });
+
+  test('returns different keys for different quality', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 640, 50, 'webp');
+    expect(a).not.toBe(b);
+  });
+
+  test('key ends with format extension', () => {
+    expect(cacheKey('/_content/img.png', 640, 75, 'webp')).toMatch(/\.webp$/);
+    expect(cacheKey('/_content/img.png', 640, 75, 'avif')).toMatch(/\.avif$/);
+    expect(cacheKey('/_content/img.png', 640, 75, 'original')).toMatch(/\.original$/);
+  });
+});
+
+describe('MIME', () => {
+  test('maps common image extensions', () => {
+    expect(MIME['.png']).toBe('image/png');
+    expect(MIME['.jpg']).toBe('image/jpeg');
+    expect(MIME['.jpeg']).toBe('image/jpeg');
+    expect(MIME['.gif']).toBe('image/gif');
+    expect(MIME['.webp']).toBe('image/webp');
+  });
+
+  test('does not include svg (handled separately)', () => {
+    expect(MIME['.svg']).toBeUndefined();
+  });
+});