@raj-dev/env-meta

Dependency-free JavaScript library for browser environment metadata: device detection (mobile, tablet, desktop), OS and browser detection, hardware info, network hints, and locale. Vanilla JS, framework-agnostic, no fingerprinting, no tracking, no IP collection. Use with React, Vue, Angular, or plain scripts.

What it does

Runs once in the client-side browser and returns a plain object describing the current environment: device type (mobile/tablet/desktop), operating system and version, browser name and version, CPU cores, approximate device memory, touch support, network connection hints (when available), optional bandwidth estimate, and locale (language and timezone). All values are derived from standard browser APIs and user-agent signals. The library does not persist, cache, or send data anywhere.

What it does not do

• Does not collect IP addresses
• Does not fingerprint or infer identity
• Does not track users or sessions
• Does not persist or cache any data
• Does not include analytics or telemetry

Suitable for use in contexts that require clear privacy guarantees (e.g. App Store review, GDPR-conscious deployments).

Data collected (high-level)

• Device: Classification as mobile, tablet, or desktop.
• OS: Operating system name and version when detectable.
• Browser: Browser name and major version when detectable.
• Hardware: Logical CPU core count, device memory tier (when exposed), and whether the device supports touch.
• Network: Connection type, effective type, downlink, RTT, and save-data preference when the Network Information API is available (not supported in Safari).
• Speed (opt-in): Optional bandwidth estimate via a small download test; only when explicitly requested.
• Locale: Primary language and timezone from the browser.

Browser support

Works in modern evergreen browsers (Chrome, Firefox, Edge, Safari). Uses only standard, non-deprecated APIs. Network Information API (navigator.connection) is not supported in Safari; the network field is then null. Speed test requires fetch and AbortController. No polyfills; the library fails gracefully and returns null for unsupported fields.

Installation

npm

npm install @raj-dev/env-meta

Usage

ESM

import EnvMeta from "@raj-dev/env-meta";

const meta = await EnvMeta.collect();
console.log(meta.device.type, meta.locale.language);

// With optional speed test
const metaWithSpeed = await EnvMeta.collect({ networkSpeed: true, timeout: 5000 });

UMD

<script src="dist/env-meta.umd.js"></script>
<script>
  EnvMeta.collect().then(function (meta) {
    console.log(meta);
  });
</script>

API

collect(options?)

Returns a Promise that resolves to a single metadata object. Safe to call in any environment; unsupported values are null or sensible defaults. Does not throw.

Options

| Option | Type | Default | Description | |------------------|---------|---------|-------------| | networkSpeed | boolean | false | If true, runs an opt-in download-based bandwidth estimate and adds a speed field. | | timeout | number | 5000 | Max time in ms for the speed test. Ignored when networkSpeed is false. | | speedTestUrl | string | (built-in) | URL used for the speed test. Override for custom endpoints. |

Return value

Object with: device, os, browser, hardware, network (or null), locale, timestamp. If networkSpeed: true, also speed with estimatedMbps and method: "download-test".

Response format

{
  "device": { "type": "mobile" | "tablet" | "desktop" },
  "os": { "name": string | null, "version": string | null },
  "browser": { "name": string | null, "version": string | null },
  "hardware": { "cores": number | null, "memoryGB": number | null, "touch": boolean },
  "network": {
    "connectionType": string | null,
    "effectiveType": string | null,
    "downlinkMbps": number | null,
    "rtt": number | null,
    "saveData": boolean
  } | null,
  "speed": { "estimatedMbps": number | null, "method": "download-test" },
  "locale": { "language": string, "timezone": string },
  "timestamp": number
}

speed is only present when networkSpeed: true is passed. network is null when the Network Information API is not available (e.g. Safari).

Support

If this library is useful to you, you can support the maintainer:

• Buy Me a Coffee
• GitHub Sponsors

License

MIT