@onderwijsin/nuxt-device

Nuxt 4 module that exposes SSR-aware device, operating-system, browser, and crawler flags through the auto-imported useDevice composable.

The logic in this module is inspired by @nuxtjs/device, but our implementation takes a different approach:

• we do not install a global plugin, making the core bundle smaller
• device flags are reactive and recalculated client side, making the module usable in prerendered routes

Do not use this module concurrently with @nuxtjs/device, because conflicts will occur.

Install and register

pnpm add @onderwijsin/nuxt-device

export default defineNuxtConfig({
  modules: ["@onderwijsin/nuxt-device"]
});

Configuration

Options are configured under device:

| Option | Type | Default | Description | | ------------------ | --------- | --------------- | --------------------------------------------------------------------------------- | | enabled | boolean | true | Disables module setup when false. | | defaultUserAgent | string | Chrome on macOS | User agent used when no request header is available, such as during prerendering. |

Use device flags

useDevice() is auto-imported by the module and returns a stable reactive object:

<script setup lang="ts">
const device = useDevice();
</script>

<template>
  <MobileNavigation v-if="device.isMobile" />
  <p v-else-if="device.isCrawler">Crawler request</p>
  <DesktopNavigation v-else />
</template>

The object includes userAgent, isMobile, isMobileOrTablet, isTablet, isDesktop, isDesktopOrTablet, isIos, isAndroid, isWindows, isLinux, isMacOS, isApple, isSafari, isFirefox, isEdge, isChrome, isSamsung, and isCrawler.

On the server, CloudFront and Cloudflare device headers take precedence for device class. Browser flags come from the user agent; operating-system flags also come from it, except CloudFront iOS and Android headers override those two flags when supplied. On the client, the browser's navigator.userAgent is used after hydration.

Compatibility and boundaries

• Requires Node.js 22 or newer and Nuxt 4.
• useDevice is the public runtime API; internal regexes and generated templates are not public imports.
• Detection is heuristic. Treat flags as presentation hints, not as an authorization or security boundary.

Development

pnpm --filter device-playground dev
pnpm --filter device-playground typecheck

Developed and tested against Node.js 24 and Nuxt 4.5.x. The package declares Node.js >=22 and may work with other Nuxt versions permitted by its package metadata, but versions outside the current CI matrix are not continuously tested. Nuxt 3 is not guaranteed.