@molecule/app-device | Molecule.dev

Device information interface for molecule.dev.

Provides device, browser, and OS detection utilities for analytics, feature detection, and platform-specific behavior.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { getDeviceInfo, supports, isStandalone } from '@molecule/app-device'

const device = getDeviceInfo() // { browser, os, isMobile, type, … }
if (device.isMobile) enableCompactNav()
if (supports('webShare')) showShareButton()
if (isStandalone()) hideInstallBanner() // already installed as a PWA

Type

core

Installation

npm install @molecule/app-device @molecule/app-bond

API

Interfaces

`BrowserInfo`

Parsed browser identity (name, version, rendering engine).

interface BrowserInfo {
  /**
   * Browser name.
   */
  name: string

  /**
   * Browser version.
   */
  version: string

  /**
   * Browser major version.
   */
  majorVersion: number

  /**
   * Browser engine (WebKit, Blink, Gecko, etc.).
   */
  engine?: string

  /**
   * Engine version.
   */
  engineVersion?: string
}

`OSInfo`

Operating system information.

interface OSInfo {
  /**
   * OS name.
   */
  name: string

  /**
   * OS version.
   */
  version: string

  /**
   * OS family (Windows, macOS, Linux, iOS, Android, etc.).
   */
  family: string
}

`DeviceInfo`

Parsed device identity (browser, OS, form factor, vendor, model, touch support).

interface DeviceInfo {
  /**
   * Full device name (OS + Browser).
   */
  name: string

  /**
   * Browser information.
   */
  browser: BrowserInfo

  /**
   * Operating system information.
   */
  os: OSInfo

  /**
   * Whether the device is mobile.
   */
  isMobile: boolean

  /**
   * Whether the device is a tablet.
   */
  isTablet: boolean

  /**
   * Whether the device is a desktop.
   */
  isDesktop: boolean

  /**
   * Device type.
   */
  type: 'mobile' | 'tablet' | 'desktop' | 'unknown'

  /**
   * Device vendor (Apple, Samsung, etc.).
   */
  vendor?: string

  /**
   * Device model (iPhone, Galaxy, etc.).
   */
  model?: string

  /**
   * Whether touch is supported.
   */
  hasTouch: boolean

  /**
   * User agent string.
   */
  userAgent: string
}

`ScreenInfo`

Screen dimensions, pixel ratio, orientation, color depth, and dark mode preference.

interface ScreenInfo {
  /**
   * Screen width in pixels.
   */
  width: number

  /**
   * Screen height in pixels.
   */
  height: number

  /**
   * Available width (minus taskbar, etc.).
   */
  availableWidth: number

  /**
   * Available height.
   */
  availableHeight: number

  /**
   * Device pixel ratio (for retina displays).
   */
  pixelRatio: number

  /**
   * Color depth.
   */
  colorDepth: number

  /**
   * Screen orientation.
   */
  orientation: 'portrait' | 'landscape'

  /**
   * Whether the device is in dark mode.
   */
  isDarkMode: boolean
}

`HardwareInfo`

Hardware capabilities (CPU cores, memory, touch points, WebGL support and renderer).

interface HardwareInfo {
  /**
   * Number of CPU cores.
   */
  cpuCores: number

  /**
   * Device memory in GB (approximate).
   */
  memory?: number

  /**
   * Maximum touch points.
   */
  maxTouchPoints: number

  /**
   * Whether the device has a GPU (canvas acceleration).
   */
  hasWebGL: boolean

  /**
   * WebGL renderer info.
   */
  webGLRenderer?: string
}

`FeatureSupport`

Feature detection results.

interface FeatureSupport {
  /**
   * Service Worker support.
   */
  serviceWorker: boolean

  /**
   * Push notifications support.
   */
  pushNotifications: boolean

  /**
   * Web Share API support.
   */
  webShare: boolean

  /**
   * Geolocation support.
   */
  geolocation: boolean

  /**
   * Media devices (camera/mic) support.
   */
  mediaDevices: boolean

  /**
   * Web Bluetooth support.
   */
  bluetooth: boolean

  /**
   * Web NFC support.
   */
  nfc: boolean

  /**
   * Vibration API support.
   */
  vibration: boolean

  /**
   * Web USB support.
   */
  webUSB: boolean

  /**
   * Web Serial support.
   */
  webSerial: boolean

  /**
   * WebAuthn/Passkeys support.
   */
  webAuthn: boolean

  /**
   * IndexedDB support.
   */
  indexedDB: boolean

  /**
   * localStorage support.
   */
  localStorage: boolean

  /**
   * WebSocket support.
   */
  webSocket: boolean

  /**
   * Fullscreen API support.
   */
  fullscreen: boolean

  /**
   * Picture-in-Picture support.
   */
  pictureInPicture: boolean

  /**
   * Web Crypto API support.
   */
  crypto: boolean

  /**
   * Clipboard API support.
   */
  clipboard: boolean
}

`DeviceProvider`

Device provider interface that all device bond packages must implement. Provides access to device, screen, hardware, and feature information.

interface DeviceProvider {
  /** Returns parsed device information (browser, OS, device type). */
  getDeviceInfo(): DeviceInfo

  /** Returns current screen dimensions, pixel ratio, and orientation. */
  getScreenInfo(): ScreenInfo

  /** Returns hardware capabilities (CPU cores, memory, WebGL). */
  getHardwareInfo(): HardwareInfo

  /** Returns browser feature support flags. */
  getFeatureSupport(): FeatureSupport

  /** Checks whether a specific browser feature is supported. */
  supports(feature: keyof FeatureSupport): boolean

  /** Returns the raw user agent string. */
  getUserAgent(): string

  /** Returns the platform identifier (e.g. `'MacIntel'`). */
  getPlatform(): string

  /** Returns the browser's preferred language (e.g. `'en-US'`). */
  getLanguage(): string

  /** Returns all browser-preferred languages in priority order. */
  getLanguages(): string[]

  /** Returns whether the device has an active network connection. */
  isOnline(): boolean

  /** Returns whether the app is running in standalone/PWA mode. */
  isStandalone(): boolean
}

Functions

`detectScreenInfo()`

Detects screen information from browser APIs (window.screen, devicePixelRatio, media queries). Returns sensible defaults in non-browser environments.

function detectScreenInfo(): ScreenInfo

Returns: A ScreenInfo object with dimensions, pixel ratio, and dark mode status.

`detectHardwareInfo()`

Detects hardware information including CPU cores, memory, touch support, and WebGL capabilities.

function detectHardwareInfo(): HardwareInfo

Returns: A HardwareInfo object with CPU, memory, and GPU details.

`detectFeatureSupport()`

Detects browser feature support by checking for the presence of APIs like Service Worker, Push, Geolocation, WebAuthn, etc.

function detectFeatureSupport(): FeatureSupport

Returns: A FeatureSupport object with boolean flags for each feature.

`parseUserAgent(ua)`

Parses a user agent string to extract browser, OS, and device type information.

function parseUserAgent(ua: string): DeviceInfo

ua — The user agent string to parse.

Returns: A DeviceInfo object with browser, OS, device type, and touch support.

`createWebDeviceProvider()`

Creates a web-based device provider that reads device, screen, hardware, and feature information from browser APIs. Results are cached except for screen info, which is refreshed on every call since it can change.

function createWebDeviceProvider(): DeviceProvider

Returns: A DeviceProvider backed by browser APIs.

`setProvider(provider)`

Registers a device provider as the active singleton.

function setProvider(provider: DeviceProvider): void

provider — The device provider implementation to bond.

`getProvider()`

Retrieves the bonded device provider. If none is bonded, automatically creates and bonds the built-in web device provider.

function getProvider(): DeviceProvider

Returns: The active device provider.

`hasProvider()`

Checks whether a device provider has been explicitly bonded.

function hasProvider(): boolean

Returns: true if a device provider is bonded.

`getDeviceInfo()`

Returns parsed user-agent data including browser, OS, and device type.

function getDeviceInfo(): DeviceInfo

Returns: The current device information from the bonded provider.

`getScreenInfo()`

Returns screen dimensions, pixel ratio, color depth, orientation, and dark mode preference.

function getScreenInfo(): ScreenInfo

Returns: The current screen information from the bonded provider.

`getHardwareInfo()`

Returns CPU cores, memory, touch points, and WebGL capabilities.

function getHardwareInfo(): HardwareInfo

Returns: The current hardware information from the bonded provider.

`getFeatureSupport()`

Returns boolean flags for all detectable browser features (Service Worker, Push, Bluetooth, etc.).

function getFeatureSupport(): FeatureSupport

Returns: The feature support map from the bonded provider.

`supports(feature)`

Checks whether a specific browser feature is supported.

function supports(feature: keyof FeatureSupport): boolean

feature — The feature key to check (e.g. 'serviceWorker', 'webAuthn', 'bluetooth').

Returns: true if the browser supports the specified feature.

`getUserAgent()`

Returns the raw user-agent string from the browser.

function getUserAgent(): string

Returns: The navigator.userAgent string.

`getPlatform()`

Returns the platform identifier (e.g. 'Win32', 'MacIntel', 'Linux x86_64').

function getPlatform(): string

Returns: The navigator.platform string.

`getLanguage()`

Returns the browser's preferred language (e.g. 'en-US').

function getLanguage(): string

Returns: The navigator.language string.

`isOnline()`

Checks whether the device currently has a network connection.

function isOnline(): boolean

Returns: true if the browser reports being online.

`isStandalone()`

Checks whether the app is running in standalone mode (installed PWA).

function isStandalone(): boolean

Returns: true if the app was launched from the home screen or app launcher.

Injection Notes

Requirements

Peer dependencies:

@molecule/app-bond ^1.0.1

Runtime Dependencies

@molecule/app-bond
Zero-config in browsers. The first call auto-bonds the built-in web provider; only non-browser platforms (native shells, SSR) need setProvider() with a platform provider.
Prefer feature detection over identity sniffing. Gate behavior on supports('feature') / getFeatureSupport(), not on browser/OS names — UA parsing is heuristic and breaks with new versions. Use getDeviceInfo() for analytics labels and coarse layout choices (isMobile/type), not for capability decisions.
isOnline() is a snapshot, not a subscription — for reactive online/offline UI, listen to the platform's connectivity events and re-read it.
Device data is client-supplied and spoofable: never use it for authorization or server-side trust decisions.

`@molecule/app-device`

How it works

Reference