@eternalscloud/user-agent

A powerful user agent parser library from Eternals Cloud for identifying client software, browsers, devices, and operating systems from HTTP user agent strings.

✨ Features

• 🔍 Comprehensive Parsing - Extract browser, device, OS, and platform information
• 📱 Device Detection - Identify mobile, tablet, and desktop devices
• 🌐 Cross-Platform - Works with all major browsers and operating systems
• ⚡ Lightweight - Minimal dependencies and fast parsing
• 📦 TypeScript Ready - Full TypeScript support with type definitions
• 🚀 Zero Dependencies - Uses only essential parsing logic
• 📦 Package Size - 15KB (45KB unpacked)

📦 Installation

npm install @eternalscloud/user-agent

yarn add @eternalscloud/user-agent

pnpm add @eternalscloud/user-agent

🚀 Quick Start

// ES6 Modules
import { userAgent } from "@eternalscloud/user-agent";

// CommonJS
const { userAgent } = require("@eternalscloud/user-agent");

// Parse a user agent string
import { userAgent } from "@eternalscloud/user-agent";

const result = userAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36");

console.log(result);

📚 API Reference

userAgent Function

Function Signature

userAgent(userAgentString: string): ParsedUserAgent

Parameters

| Parameter | Type | Description | |-----------|------|-------------| | userAgentString | string | The user agent string to parse |

Return Object Structure

{
  "browser": "Chrome",
  "version": "119.0.0.0",
  "os": "Windows 10.0",
  "platform": "Microsoft Windows",
  "source": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
  "device_type": "web"
}

Return Object Properties

| Property | Type | Description | |----------|------|-------------| | browser | string | Browser name (Chrome, Firefox, Safari, etc.) | | version | string | Browser version | | os | string | Operating system name and version | | platform | string | Platform information | | source | string | Original user agent string | | device_type | string | Device type: "mobile", "tab", or "web" |

💡 Usage Examples

Basic Parsing

import { userAgent } from "@eternalscloud/user-agent";

const parsed = userAgent(req.headers['user-agent']);

console.log(`Browser: ${parsed.browser} ${parsed.version}`);
console.log(`Device: ${parsed.device_type}`);
console.log(`OS: ${parsed.os}`);

Express.js Integration

import express from 'express';
import { userAgent } from "@eternalscloud/user-agent";

const app = express();

app.get('/', (req, res) => {
  const deviceInfo = userAgent(req.headers['user-agent']);
  
  res.json({
    message: 'Hello World',
    device: deviceInfo
  });
});

React/Next.js

import { userAgent } from "@eternalscloud/user-agent";

function MyComponent() {
  const [deviceInfo, setDeviceInfo] = useState(null);
  
  useEffect(() => {
    const parsed = userAgent(navigator.userAgent);
    setDeviceInfo(parsed);
  }, []);
  
  return (
    <div>
      {deviceInfo && (
        <p>You're using {deviceInfo.browser} on {deviceInfo.os}</p>
      )}
    </div>
  );
}

TypeScript Usage

import { userAgent } from "@eternalscloud/user-agent";

const result = userAgent("Mozilla/5.0...");

// Type-safe access to properties
if (result.browser === 'Chrome') {
  console.log(`Chrome version: ${result.version}`);
}

🌐 Supported Browsers & Devices

Browsers

• ✅ Chrome, Firefox, Safari, Edge
• ✅ Internet Explorer (all versions)
• ✅ Mobile browsers (Chrome Mobile, Safari Mobile, etc.)
• ✅ Bot and crawler detection

Operating Systems

• ✅ Windows (all versions)
• ✅ macOS (all versions)
• ✅ Linux distributions
• ✅ iOS and Android
• ✅ Other mobile platforms

Device Types

• ✅ Desktop computers
• ✅ Mobile phones
• ✅ Tablets
• ✅ Smart TVs and other devices

📄 License

• Package: MIT License
• Source Code: MIT License

License Summary

• ✅ Free for commercial and personal use
• ✅ Can be used in proprietary software
• ✅ Can be modified and redistributed
• ✅ No attribution required (but appreciated)