web-platform-kit

A tiny TypeScript user-agent & platform detector — resolves OS, browser, engine, and device from the UA string, then refines the result with User-Agent Client Hints (high-entropy) when available.

npm install web-platform-kit

API at a glance

PlatformKit is a singleton. All detection fields are getters.

| Member | Type | Description | |------------------------------------| --- | --- | | PlatformKit.version | string | The installed package version | | PlatformKit.ready | Promise<void> | Resolves once async UA Client Hints have merged in | | PlatformKit.userAgent | string (get/set) | Read the active UA string, or set one to parse a custom UA | | PlatformKit.os | { name, version } | name: unknown \| windows \| macos \| android \| ios | | PlatformKit.browser | { name, version } | name: unknown \| chrome \| safari \| edge \| firefox \| opera \| ie \| samsung | | PlatformKit.engine | { name, version } | name: blink \| webKit \| gecko \| presto \| trident \| … | | PlatformKit.device | string | unknown \| mobile \| desktop | | PlatformKit.webview | boolean | Whether running inside a WebView | | PlatformKit.node | boolean | Whether running under Node.js | | PlatformKit.standalone | boolean | Whether launched as an installed PWA | | PlatformKit.compareVersion(a, b) | -1 \| 0 \| 1 | Numeric dotted-version comparison (named export) |

About ready: on Chromium, the most accurate OS/browser version comes from User-Agent Client Hints, which resolve asynchronously. Read fields after await PlatformKit.ready for best accuracy; before it resolves you still get a synchronous result parsed from the UA string.

ESM

import PlatformKit from 'web-platform-kit'

// Synchronous (UA-string based) — available immediately
console.log(PlatformKit.os)      // { name: 'ios', version: '17.4' }
console.log(PlatformKit.browser) // { name: 'safari', version: '17.4' }
console.log(PlatformKit.device)  // 'mobile'

// Refined with Client Hints (Chromium) — await first
await PlatformKit.ready
console.log(PlatformKit.os.version) // full platform version on Chromium

// Version gate
if (PlatformKit.compareVersion(PlatformKit.os.version, '15.0') >= 0) {
  // iOS 15+
}

CommonJS

The bundle is built with exports: "named", so the singleton lives under .default:

const { default: PlatformKit } = require('web-platform-kit')

console.log(PlatformKit.browser.name, PlatformKit.browser.version)

UMD (browser <script>)

The global PlatformKit is a namespace object. The singleton is PlatformKit.default; the helper is PlatformKit.compareVersion.

<script src="https://unpkg.com/web-platform-kit/dist/platform-kit.umd.min.js"></script>
<script>
    var p = window.PlatformKit.default

    document.body.dataset.os = p.os.name
    document.body.dataset.browser = p.browser.name

    if (p.webview) {
        console.log('running inside a WebView')
    }
</script>

TypeScript

The { name, version } shape is exported as NameVersionPair<T>; the singleton shape is PlatformKitInstance. The os / browser / engine / device name unions are exported too (OS, Browsers, Engines, Devices).

import PlatformKit, {
  type OS,
  type NameVersionPair,
} from 'web-platform-kit'

const os: NameVersionPair<OS> = PlatformKit.os

function isModernSafari(): boolean {
  return PlatformKit.browser.name === 'safari'
    && PlatformKit.compareVersion(PlatformKit.browser.version, '16.0') >= 0
}

Parsing a custom UA string

Set userAgent to parse an arbitrary string — useful server-side or in tests. Setting a custom UA parses purely from that string (no Client Hints merge).

import PlatformKit from 'web-platform-kit'

PlatformKit.userAgent = 'Mozilla/5.0 (Linux; Android 14; Pixel 8) ' +
  'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Mobile Safari/537.36'

console.log(PlatformKit.os)      // { name: 'android', version: '14' }
console.log(PlatformKit.browser) // { name: 'chrome', version: '124.0' }

Note: userAgent is shared singleton state — setting it changes detection globally for every reader. Restore PlatformKit.userAgent if other code relies on the real environment.

Notes

• Detection is best-effort. User agents are spoofable and inconsistent across vendors; treat the result as a strong hint, not ground truth. Prefer feature detection for capability decisions where possible.
• Client Hints are Chromium-only and async. Non-Chromium browsers resolve ready immediately with UA-string parsing; os.version granularity is limited to what the UA string exposes there.
• iPadOS reports as desktop. iPadOS Safari sends a macOS UA; this library re-classifies it as ios when navigator.standalone is present and maxTouchPoints > 2, but edge cases remain.
• .default in CJS/UMD is a consequence of keeping both a default and named exports. To drop it, switch the entry to fully-named exports and rebuild.