Device-aware routing
Rewrite requests differently for mobile and desktop clients.
Next.js 16+ · Function
userAgent
userAgent parses a request's user-agent data into bot, browser, device, engine, and operating-system details. It is imported from next/server and is commonly used with NextRequest in Proxy logic.
How it works
Import userAgent from next/server and pass it a NextRequest in Proxy or another request-aware server context. The returned object exposes parsed bot, browser, device, engine, and operating-system details; individual values can be undefined when the user agent cannot identify them.
Syntax
userAgent(request)Parameters
| Name | Type | Description |
|---|---|---|
request | NextRequest | The incoming request whose user-agent information should be parsed. |
Returns
An object containing isBot and parsed browser, device, engine, and operating-system information.
Key points
- userAgent augments request handling with parsed user-agent metadata.
- The isBot field identifies requests from recognized bots.
- The browser object describes the detected browser.
- The device object describes the detected client device.
- The os object contains operating-system information.
- A Proxy function can receive a NextRequest and pass it to userAgent.
Common mistakes
- It is a request helper, not a replacement for the standard Web Request API.
- Browser identification is not guaranteed, so code must handle an undefined browser name.
- Device type may be undefined and should be treated as optional.
Example: Classify a request in Proxy
import { NextRequest, NextResponse, userAgent } from 'next/server'
export function proxy(request: NextRequest) {
const { device, isBot } = userAgent(request)
const viewport = device.type === 'mobile' ? 'mobile' : 'desktop'
request.nextUrl.searchParams.set('viewport', viewport)
request.nextUrl.searchParams.set('bot', String(isBot))
return NextResponse.rewrite(request.nextUrl)
}This proxy classifies the incoming request using parsed device and bot information, then rewrites the URL with those values.
When to use it
Bot-aware processing
Detect recognized crawlers before applying request handling rules.
Request classification
Collect browser, engine, or operating-system metadata for server-side decisions.
Interview questions
QWhat does userAgent return?
userAgent parses the incoming request and returns structured information about the user agent. The result includes isBot plus browser, device, engine, and operating-system objects.
Follow-up: How should device-dependent routing handle unknown clients? Use a conservative default when device.type is undefined rather than assuming mobile or desktop.
QHow is the helper used in Proxy?
Call userAgent with the request object, commonly a NextRequest received by Proxy. For example, userAgent(request) can provide device.type for a rewrite decision.
Follow-up: Why use NextRequest instead of constructing a new Request? NextRequest supplies Next.js request context such as nextUrl, which is useful when applying the parsed result to a rewrite.
QWhat metadata does the result expose?
The isBot property is a boolean that indicates whether the request comes from a known bot. Browser, device, engine, and operating-system fields provide parsed metadata, with some fields possibly undefined.
Follow-up: What should code do with uncertain browser metadata? Treat absent names, versions, models, and types as unknown and avoid relying on them as mandatory values.
Related
NextRequestNextResponseproxyProxyrequest.nextUrldevicebrowserengine