undevice
v1.2.2
Published
Runtime-agnostic user-agent device detector
Maintainers
Readme
undevice
Unified Device Detector
Device, OS, and browser detection from User-Agent and CDN headers. Works in Node.js, browsers, and edge runtimes without framework dependencies.
- ESM with TypeScript types.
- Cloudflare and CloudFront header support.
- Custom detection flags.
- Dependency-free.
- Adapters: Express, Fastify.
Not affiliated with the UnJS organization.
Contents
Install
npm install undeviceAgent skill
Install the undevice skill to help your coding agent use the API, configure custom flags, and integrate detection into request handlers and SSR.
npx skills add teplostanski/undevice --skill undeviceFor Express middleware and route types, use the Express skill.
npx skills add teplostanski/undevice --skill undevice-expressFor Fastify plugins and route types, use the Fastify skill.
npx skills add teplostanski/undevice --skill undevice-fastifyUsage
Create a detector once, then pass each request's headers to detect():
import { undevice } from 'undevice'
const { detect } = undevice()
const device = detect({ headers: request.headers })
device.isMobile
device.isTablet
device.isDesktopSee the documentation for input options, flags, and API details.
Custom flags
import { undevice } from 'undevice'
const { detect } = undevice({ isRawClient: ['curl', 'wget'] })
const device = detect({ userAgent: 'curl/8.0' })
device.isRawClient // trueSee Custom flags for callbacks, exclusions, and more examples.
Adapters
Express
import express from 'express'
import { undevice } from 'undevice/express'
const app = express()
app.use(undevice())
app.get('/device', (_req, res) => {
res.json(res.locals.undevice)
})See the Express guide for custom flags and TypeScript declarations.
Fastify
import Fastify from 'fastify'
import { undevice } from 'undevice/fastify'
const app = Fastify()
await app.register(undevice())
app.get('/device', async (request, reply) => {
return reply.send(request.undevice)
})See the Fastify guide for custom flags and TypeScript declarations.
CloudFront
When the User-Agent matches Amazon CloudFront case-insensitively, the following headers are checked:
CloudFront-Is-Android-ViewerCloudFront-Is-Desktop-ViewerCloudFront-Is-IOS-ViewerCloudFront-Is-Mobile-ViewerCloudFront-Is-Tablet-Viewer
Pass request headers via headers. If no device type header is true,
the result includes isUnknown: true.
[!CAUTION] CloudFront does not provide headers for detecting Windows or macOS.
Configure device type headers in CloudFront.
Cloudflare
If the CloudFront rule does not apply and CF-Device-Type is mobile, tablet,
or desktop, that value takes precedence over the User-Agent for device type
detection. If the header is missing or its value is unrecognized, detection
falls back to the User-Agent.
Configure Cache by device type in Cloudflare APO.
Compatibility
Node.js 22+. ESM only. Browsers and edge runtimes must support ES2022 APIs.
Credits
Inspired by @nuxtjs/device.
License
MIT License © 2026-PRESENT Teplostanski Igor
