@eternalscloud/user-agent

@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)

Made with ❤️ by Eternals Cloud