0
# Platform.js
1

2
Platform.js is a platform detection library that works on nearly all JavaScript platforms. It provides a unified API for detecting browser, operating system, device, and environment information from user agent strings. The library automatically analyzes the runtime environment and exposes detailed platform information through a simple object interface.
3

4
## Package Information
5

6
- **Package Name**: platform
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install platform`
10

11
## Core Imports
12

13
ES6/TypeScript:
14

15
```javascript
16
import platform from "platform";
17
```
18

19
CommonJS:
20

21
```javascript
22
const platform = require("platform");
23
// Or import individual properties
24
const { name, version, os, parse } = require("platform");
25
```
26

27
AMD/RequireJS:
28

29
```javascript
30
define(["platform"], function(platform) {
31
  // use platform
32
});
33
```
34

35
Browser (Global):
36

37
```html
38
<script src="platform.js"></script>
39
<script>
40
  // platform is available globally
41
  console.log(platform.name);
42
</script>
43
```
44

45
## Basic Usage
46

47
```javascript
48
// Detect current environment automatically
49
console.log(platform.name);        // "Chrome"
50
console.log(platform.version);     // "91.0.4472.124"
51
console.log(platform.os.family);   // "Windows"
52
console.log(platform.os.version);  // "10"
53
console.log(platform.description); // "Chrome 91.0.4472.124 on Windows 10 64-bit"
54

55
// Parse custom user agent string
56
const info = platform.parse("Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15");
57
console.log(info.name);        // "Safari"
58
console.log(info.product);     // "iPhone"
59
console.log(info.os.family);   // "iOS"
60
console.log(info.os.version);  // "14.6"
61
```
62

63
## Capabilities
64

65
### Platform Detection Properties
66

67
Access current environment information through the main platform object properties.
68

69
```javascript { .api }
70
/**
71
 * The main platform object containing environment detection information
72
 */
73
declare const platform: {
74
  /** The complete platform description string */
75
  description: string | null;
76
  
77
  /** The name of the browser's layout engine (e.g., "Blink", "Gecko", "WebKit") */
78
  layout: string | null;
79
  
80
  /** The name of the product's manufacturer (e.g., "Apple", "Google", "Microsoft") */
81
  manufacturer: string | null;
82
  
83
  /** The name of the browser/environment (e.g., "Chrome", "Firefox", "Safari") */
84
  name: string | null;
85
  
86
  /** The alpha/beta release indicator */
87
  prerelease: string | null;
88
  
89
  /** The name of the product hosting the browser (e.g., "iPad", "iPhone") */
90
  product: string | null;
91
  
92
  /** The browser's user agent string */
93
  ua: string | null;
94
  
95
  /** The browser/environment version */
96
  version: string | null;
97
  
98
  /** Operating system information object */
99
  os: OSInfo;
100
  
101
  /** Parse a custom user agent string */
102
  parse(ua?: string | object): PlatformInfo;
103
  
104
  /** Return platform description as string */
105
  toString(): string;
106
};
107
```
108

109
### Operating System Detection
110

111
Access detailed operating system information through the `platform.os` object.
112

113
```javascript { .api }
114
interface OSInfo {
115
  /** The CPU architecture the OS is built for (32 or 64) */
116
  architecture: number | null;
117
  
118
  /** The family/name of the OS (e.g., "Windows", "OS X", "Linux", "iOS") */
119
  family: string | null;
120
  
121
  /** The version of the OS */
122
  version: string | null;
123
  
124
  /** Returns the OS string representation */
125
  toString(): string;
126
}
127
```
128

129
### User Agent Parsing
130

131
Parse custom user agent strings to extract platform information.
132

133
```javascript { .api }
134
/**
135
 * Creates a new platform object by parsing a user agent string or context object
136
 * @param ua - The user agent string or context object (defaults to navigator.userAgent in browsers)
137
 * @returns A platform object with the same structure as the main platform object
138
 */
139
function parse(ua?: string | object): PlatformInfo;
140

141
interface PlatformInfo {
142
  description: string | null;
143
  layout: string | null;
144
  manufacturer: string | null;
145
  name: string | null;
146
  prerelease: string | null;
147
  product: string | null;
148
  ua: string | null;
149
  version: string | null;
150
  os: OSInfo;
151
  parse(ua?: string | object): PlatformInfo;
152
  toString(): string;
153
}
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
// Parse iPhone user agent
160
const iphone = platform.parse("Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15");
161
console.log(iphone.name);           // "Safari"
162
console.log(iphone.product);        // "iPhone"
163
console.log(iphone.manufacturer);   // "Apple"
164
console.log(iphone.os.family);      // "iOS"
165
console.log(iphone.os.version);     // "14.6"
166

167
// Parse Chrome on Windows user agent
168
const chrome = platform.parse("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36");
169
console.log(chrome.name);           // "Chrome"
170
console.log(chrome.version);        // "91.0.4472.124"
171
console.log(chrome.layout);         // "Blink"
172
console.log(chrome.os.family);      // "Windows"
173
console.log(chrome.os.version);     // "10"
174
console.log(chrome.os.architecture); // 64
175

176
// Parse with context object
177
const customContext = {
178
  navigator: {
179
    userAgent: "Mozilla/5.0 (iPad; CPU OS 14_6 like Mac OS X) AppleWebKit/605.1.15",
180
    platform: "MacIntel"
181
  }
182
};
183
const ipad = platform.parse(customContext);
184
console.log(ipad.product);          // "iPad"
185
console.log(ipad.os.family);        // "iOS"
186
```
187

188
### String Conversion
189

190
Convert platform objects to string representations for display or logging.
191

192
```javascript { .api }
193
/**
194
 * Returns platform description when the platform object is coerced to a string
195
 * @returns The platform description if available, else an empty string
196
 */
197
function toString(): string;
198
```
199

200
**Usage Examples:**
201

202
```javascript
203
// Main platform object string conversion
204
console.log(platform.toString());
205
// "Chrome 91.0.4472.124 on Windows 10 64-bit"
206

207
console.log(String(platform));
208
// "Chrome 91.0.4472.124 on Windows 10 64-bit"
209

210
// OS object string conversion  
211
console.log(platform.os.toString());
212
// "Windows 10 64-bit"
213

214
// Parsed platform string conversion
215
const mobile = platform.parse("Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X)");
216
console.log(mobile.toString());
217
// "Safari 14.6 on Apple iPhone (iOS 14.6)"
218
```
219

220
## Common Patterns
221

222
### Environment Detection
223

224
```javascript
225
// Detect mobile vs desktop
226
const isMobile = platform.product && 
227
  /iPad|iPhone|Android|BlackBerry|Windows Phone/i.test(platform.product);
228

229
// Detect specific browsers
230
const isChrome = platform.name === 'Chrome';
231
const isSafari = platform.name === 'Safari';
232
const isFirefox = platform.name === 'Firefox';
233

234
// Detect operating systems
235
const isWindows = platform.os.family && platform.os.family.indexOf('Windows') === 0;
236
const isMac = platform.os.family === 'OS X';
237
const isLinux = platform.os.family === 'Linux';
238
const isIOS = platform.os.family === 'iOS';
239
const isAndroid = platform.os.family === 'Android';
240

241
// Check architecture
242
const is64Bit = platform.os.architecture === 64;
243
```
244

245
### User Agent Analysis
246

247
```javascript
248
// Analyze multiple user agents
249
const userAgents = [
250
  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
251
  "Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X)",
252
  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36"
253
];
254

255
const analysis = userAgents.map(ua => {
256
  const info = platform.parse(ua);
257
  return {
258
    browser: info.name,
259
    version: info.version,
260
    os: info.os.family,
261
    device: info.product || 'Desktop',
262
    description: info.toString()
263
  };
264
});
265

266
console.log(analysis);
267
```
268

269
### Feature Detection Alternative
270

271
```javascript
272
// While platform.js is informational, you can combine with feature detection
273
function getEnvironmentInfo() {
274
  return {
275
    // Platform detection (informational)
276
    browser: platform.name,
277
    os: platform.os.family,
278
    mobile: platform.product && /mobile|tablet/i.test(platform.product),
279
    
280
    // Feature detection (for functionality)
281
    touch: 'ontouchstart' in window,
282
    webgl: !!window.WebGLRenderingContext,
283
    localStorage: typeof localStorage !== 'undefined',
284
    history: !!(window.history && history.pushState)
285
  };
286
}
287
```