nuxt-http-client-hints

0.0.2 verified Sat Apr 25 auth: no javascript

Nuxt module providing HTTP Client Hints for server-side browser, OS, device, network, and critical hints detection in Nuxt 3. Current version 0.0.2, weekly release pair. Only supported in Chromium-based browsers (Chrome, Edge, Chromium, Opera) due to draft spec status. Uses detect-browser-es internally. Grants access to Client Hints headers like Device-Memory, Save-Data, Downlink, ECT, RTT, and various Sec-CH-UA headers on the server via Nuxt plugins and composables.

Common errors

error Cannot find module '#http-client-hints' or its corresponding type declarations. ↓

cause The module's auto-import pattern may not be recognized by TypeScript without proper Nuxt types generation.

fix

Run nuxi prepare or nuxi generate to generate the Nuxt types. Ensure the module is added to the modules array in nuxt.config.ts.

error TypeError: Cannot read properties of null (reading 'deviceMemory') ↓

cause Client Hints are not sent by the browser, so the composable returns null for all values.

fix

Check for browser support: navigator.userAgentData?.getHighEntropyValues() as fallback. Or wrap usage in null checks.

error Nuxt module 'nuxt-http-client-hints' is not compatible with Nuxt 2. ↓

cause This module only supports Nuxt 3 (v3.x).

fix

Upgrade to Nuxt 3 or use an alternative package.

Warnings

gotcha HTTP Client Hints are only supported in Chromium-based browsers (Chrome, Edge, Chromium, Opera). Firefox, Safari, and other browsers send no Client Hints headers, resulting in null/undefined values. ↓

fix Check for null values before using hints. Consider using a User-Agent fallback for non-Chromium browsers.

gotcha The module relies on the detect-browser-es package, which may have peer dependency conflicts if another version is installed. ↓

fix Ensure only one version of detect-browser-es is in your lockfile.

gotcha The Client Hints spec is still in draft and headers may change or be removed. Current implementation may break with future browser updates. ↓

fix Keep the module updated and monitor MDN or WICG spec changes.

gotcha Module version 0.0.2 has no stable release yet; breaking changes may occur between patches. ↓

fix Pin to exact version and re-evaluate updates.

Install

npm install nuxt-http-client-hints

yarn add nuxt-http-client-hints

pnpm add nuxt-http-client-hints

Imports

useHttpClientHints
wrong
```
import { useHttpClientHints } from 'nuxt-http-client-hints'
```
correct
```
import { useHttpClientHints } from '#http-client-hints'
```
The composable is auto-imported; explicit import uses the alias #http-client-hints when module is installed.
defineHttpClientHintsConfig
```
import { defineHttpClientHintsConfig } from 'nuxt-http-client-hints'
```
Available in version >= 0.0.1 for runtime config.

HttpClientHintsPlugin

wrong

import { HttpClientHintsPlugin } from 'nuxt-http-client-hints'

correct

import { HttpClientHintsPlugin } from 'nuxt-http-client-hints/runtime/plugin'

Plugin is internal; use the module's Nuxt module setup instead of plugin directly.

Quickstart

Shows Nuxt module registration and usage of useHttpClientHints composable and server-side header access.

// Module registration in nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-http-client-hints'],
  httpClientHints: {
    // Optional: configure client hints to use
    deviceMemory: true,
    downlink: true,
    ect: true,
    rtt: true,
    secCHPrefersColorScheme: true,
  }
})

// In any component/page
const hints = useHttpClientHints()
console.log(hints.deviceMemory) // '4' | '2' | '1' | '0.5' | '0.25' | null
console.log(hints.downlink) // e.g., '10' (Mbps)
console.log(hints.ect) // '4g' | '3g' | '2g' | 'slow-2g' | null
console.log(hints.rtt) // RTT in milliseconds
console.log(hints.secCHPrefersColorScheme) // 'light' | 'dark' | null

// Server-side usage via event
// In server/api or server middleware
export default defineEventHandler(async (event) => {
  // Access client hints from request headers
  const deviceMemory = getRequestHeader(event, 'Device-Memory')
  // ...
})