Skip to content

feat: add Client Hints support for improved cold-start detection#113

Open
superbiche wants to merge 1 commit into
mvrlin:mainfrom
superbiche:feat/client-hints
Open

feat: add Client Hints support for improved cold-start detection#113
superbiche wants to merge 1 commit into
mvrlin:mainfrom
superbiche:feat/client-hints

Conversation

@superbiche

Copy link
Copy Markdown

Summary

Implements the Client Hints detection proposed in #110, extending the existing utils.ts as suggested by @mvrlin.

  • Opt-in via clientHints: true | { viewportWidth, critical } in module config
  • Detection chain becomes: cookie → Client Hints → CDN headers → UA → fallback
  • Zero behavior change without the clientHints option — fully backward compatible

What's included

  • types.ts: new ClientHintsOptions type + clientHints property on ViewportOptions
  • utils.ts: Sec-CH-Viewport-Width (pixel-accurate) and Sec-CH-UA-Mobile (default on Chromium) detection, plus resolveBreakpointFromWidth() helper
  • plugin.server.ts: sets Accept-CH / Critical-CH response headers when viewportWidth is enabled

Design choices worth noting

This implementation takes a different approach from #112:

  • Non-breaking: extends existing detectBreakpoint() instead of rewriting it — no API surface changes, no removed functions
  • Breakpoint-aware width resolution: Sec-CH-Viewport-Width maps to configured breakpoints using the minWidth/maxWidth feature mode, rather than a hardcoded threshold
  • Respects defaultBreakpoints: Sec-CH-UA-Mobile maps through the existing config (e.g. mobile → "sm") instead of returning raw device type strings
  • Full Client Hints lifecycle: includes Accept-CH and Critical-CH response header negotiation, which is required for browsers to send Sec-CH-Viewport-Width
  • Preserves dynamic import: keeps Bowser behind import() for chunk splitting

~98 lines added across 3 files.

Test plan

  • Verify default behavior unchanged (no clientHints config)
  • Enable clientHints: true — confirm Sec-CH-UA-Mobile detection works on Chromium
  • Enable clientHints: { viewportWidth: true } — confirm Accept-CH header is set and width-based detection resolves to correct breakpoint
  • Enable clientHints: { viewportWidth: true, critical: true } — confirm Critical-CH header is set
  • Non-Chromium browsers fall back to UA detection gracefully

Adds opt-in HTTP Client Hints (Sec-CH-UA-Mobile, Sec-CH-Viewport-Width)
to the detection chain, improving first-visit accuracy for tablets,
split-screen, and iPads in desktop mode.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant