useRequestEvent, useRequestHeaders, useRequestURL Reference

Nuxe exposes four server-aware composables for reading the incoming HTTP request during SSR. All four are safe to call in isomorphic code: on the client they return empty values (undefined, {}, the current location, or the plain $fetch client) rather than throwing. This lets you write a single composable that works on both the server and the client without conditional guards.

These composables return meaningful data only on the server during an SSR render. Calling them from a client-side event handler or lifecycle hook after hydration will return the documented fallback values.

`useRequestEvent`

Returns the raw incoming Request object for the current SSR render. This is the standard Fetch API Request, giving you access to .url, .method, .headers, and the full request body.

Signature

useRequestEvent(): Request | undefined

Return value

(return value)

Request | undefined

The incoming Request on the server, or undefined on the client.

`useRequestHeaders`

Returns a plain object containing all incoming request headers. Header names are lowercased (as per the Fetch API Headers normalization).

Signature

useRequestHeaders(): Record<string, string>

Return value

(return value)

Record<string, string>

A { [headerName]: value } map on the server, or an empty object ({}) on the client.

`useRequestURL`

Constructs and returns a URL object for the current request. On the server it parses the incoming request URL, optionally using X-Forwarded-Host and X-Forwarded-Proto headers to reconstruct the public-facing origin when Nuxe runs behind a reverse proxy.

Signature

useRequestURL(opts?: {
  xForwardedHost?: boolean
  xForwardedProto?: boolean
}): URL

opts.xForwardedHost

boolean

default:"true"

When true (the default), the X-Forwarded-Host request header is used as the hostname component of the URL. Set to false to always use the Host header regardless of proxy headers.

opts.xForwardedProto

boolean

default:"true"

When true (the default), the X-Forwarded-Proto header is used to determine the protocol (http or https). Set to false to fall back to X-Real-Proto or http.

Return value

(return value)

URL

A standard URL instance. On the server this reflects the incoming request URL (with proxy header resolution applied). On the client this is new URL(globalThis.location.href).

`useRequestFetch`

Returns a $Fetch instance that forwards the incoming server request’s headers (cookies, authorization, etc.) to outgoing fetch calls. Use this when you need to proxy authenticated requests to an upstream API during SSR.

Signature

useRequestFetch(event?: { req?: { headers?: Headers; url?: string } }): $Fetch

event

{ req?: { headers?: Headers; url?: string } }

An optional object supplying a custom request context. When omitted, useRequestFetch reads headers and URL from the current SSR context automatically via useNuxeApp(). Pass an explicit event when you need to forward headers from a different request (e.g. inside a Nuxe server plugin).

Return value

(return value)

$Fetch

On the server: a $Fetch instance pre-configured with the incoming request headers and a baseURL derived from the incoming request origin. Relative URLs are automatically resolved against that base. Absolute URLs are sent as-is without a base.On the client: the plain global $fetch instance (no special headers are injected).

Examples

Reading a specific header in a composable

// composables/use-locale-from-header.ts
import { useRequestHeaders } from '@dvlkit/nuxe'

export function useLocaleFromHeader(): string {
  const headers = useRequestHeaders()
  // e.g. "en-US,en;q=0.9"
  const acceptLanguage = headers['accept-language'] ?? ''
  return acceptLanguage.split(',')[0]?.split(';')[0]?.trim() ?? 'en'
}

Forwarding cookies to an upstream API during SSR

// server/use-profile.ts
import { useRequestFetch } from '@dvlkit/nuxe'

export async function fetchProfile() {
  // On the server, $fetch is bound to the SSR request — session cookie is forwarded.
  // On the client, $fetch is the regular global instance (browser sends its own cookies).
  const fetch = useRequestFetch()
  return fetch<{ name: string; avatar: string }>('/api/me')
}

Building a canonical URL

import { useRequestURL } from '@dvlkit/nuxe'

// In a page component's setup()
const url = useRequestURL()
// url.pathname === '/products/42'
// url.origin   === 'https://store.example.com'  (resolved via X-Forwarded-* headers)

useHead({
  link: [{ rel: 'canonical', href: url.href }],
})

Accessing the raw Request object

import { useRequestEvent } from '@dvlkit/nuxe'

const request = useRequestEvent()

if (request) {
  // Server-side only
  const method = request.method           // 'GET'
  const auth   = request.headers.get('authorization')  // 'Bearer …' or null
}

Do not call useRequestEvent() or useRequestHeaders() inside client-side lifecycle hooks such as onMounted. They will return undefined / {} and the data will not be available. These composables are only meaningful in the synchronous part of setup() during SSR.

Use useRequestFetch instead of the global $fetch inside server-only useAsyncData handlers when your API requires authentication. It transparently forwards the user’s session cookie without any extra configuration.

Configuration

Composables

CLI

useRequestEvent, useRequestHeaders, useRequestURL Reference