@oxog/env-scout

A comprehensive, lightweight, and zero-dependency environment detection library for JavaScript/TypeScript applications. Detect runtime environments, browsers, operating systems, devices, and features with ease.

Features

• Zero Dependencies - No external dependencies, keeping your bundle size minimal
• TypeScript Support - Full TypeScript support with comprehensive type definitions
• Tree-Shakeable - Import only what you need
• Cached Results - Automatic caching for performance optimization
• Comprehensive Detection - Detect runtime, browser, OS, device, network, and features
• Cross-Platform - Works in browsers, Node.js, Bun, Deno, and more

Installation

# npm
npm install @oxog/env-scout

# yarn
yarn add @oxog/env-scout

# pnpm
pnpm add @oxog/env-scout

# bun
bun add @oxog/env-scout

Quick Start

import { isBrowser, getEnvironmentInfo, isEnvironment } from '@oxog/env-scout';

// Simple checks
if (isBrowser() && isDarkMode()) {
  // Apply dark theme
}

// Multiple conditions
if (isEnvironment(['browser', 'mobile', 'online'])) {
  // Mobile browser with connection
}

// Get complete info
const env = getEnvironmentInfo();
console.log(env);
// {
//   runtime: 'browser',
//   browser: { name: 'chrome', version: '120' },
//   os: 'macos',
//   device: { type: 'desktop', touch: true, retina: true },
//   ...
// }

API Documentation

Runtime Environment Detection

| Function | Description | |----------|-------------| | isBrowser() | Running in web browser | | isNode() | Running in Node.js | | isBun() | Running in Bun runtime | | isDeno() | Running in Deno runtime | | isElectron() | Running in Electron | | isJsDom() | Running in jsdom | | isReactNative() | Running in React Native | | isCapacitor() | Running in Capacitor | | isCordova() | Running in Cordova | | isTauri() | Running in Tauri | | isWebWorker() | Any web worker | | isDedicatedWorker() | Dedicated worker | | isSharedWorker() | Shared worker | | isServiceWorker() | Service worker |

Browser Detection

| Function | Description | |----------|-------------| | isChrome() | Google Chrome browser | | isFirefox() | Mozilla Firefox browser | | isSafari() | Apple Safari browser | | isEdge() | Microsoft Edge browser | | isOpera() | Opera browser | | getBrowser() | Returns { name: string, version: string } | | isHeadlessBrowser() | Detect headless browsers |

Operating System Detection

| Function | Description | |----------|-------------| | isMacOs() | macOS operating system | | isWindows() | Windows operating system | | isLinux() | Linux operating system | | isIos() | iOS operating system | | isAndroid() | Android operating system | | getOS() | Returns OS name as string |

Device Detection

| Function | Description | |----------|-------------| | isMobile() | Mobile device | | isTablet() | Tablet device | | isDesktop() | Desktop device | | isTouchDevice() | Has touch support | | isRetina() | High DPI display | | getDeviceType() | Returns device type string |

Screen & Display

| Function | Description | |----------|-------------| | getScreenSize() | Returns { width: number, height: number } | | getOrientation() | Returns 'portrait' \| 'landscape' | | isSmallScreen() | Screen width < 576px | | isMediumScreen() | Screen width 576px - 1200px | | isLargeScreen() | Screen width >= 1200px |

User Preferences

| Function | Description | |----------|-------------| | isDarkMode() | Prefers dark color scheme | | isLightMode() | Prefers light color scheme | | prefersReducedMotion() | Prefers reduced motion | | getColorScheme() | Returns 'dark' \| 'light' \| 'no-preference' | | getSystemLanguage() | Returns language code | | getTimezone() | Returns user timezone |

Network & Connection

| Function | Description | |----------|-------------| | isOnline() | Has network connection | | isOffline() | No network connection | | getConnectionType() | Returns connection type (wifi, cellular, etc.) | | isSlowConnection() | Slow network connection | | getConnectionInfo() | Complete connection details |

Feature Detection

| Function | Description | |----------|-------------| | isHTTPS() | Secure HTTPS connection | | hasWebGL() | WebGL support | | hasWebGL2() | WebGL2 support | | hasCanvas() | Canvas support | | hasWebAssembly() | WebAssembly support | | hasServiceWorkerSupport() | Service Worker support | | hasNotificationSupport() | Notification API support | | hasGeolocationSupport() | Geolocation API support |

Special Detection

| Function | Description | |----------|-------------| | isBot() | Search engine bot | | isPWA() | Progressive Web App | | isStandalone() | PWA standalone mode | | isIframe() | Running in iframe | | isLocalhost() | Local development | | isDevelopment() | Development environment | | isProduction() | Production environment |

Utility Functions

getEnvironmentInfo()

Returns complete environment information:

const info = getEnvironmentInfo();
// {
//   runtime: 'browser',
//   browser: { name: 'chrome', version: '120' },
//   os: 'windows',
//   device: { type: 'desktop', touch: false, retina: true },
//   screen: { width: 1920, height: 1080, orientation: 'landscape' },
//   network: { online: true, type: '4g', slow: false },
//   features: { webgl: true, canvas: true, ... },
//   preferences: { colorScheme: 'dark', reducedMotion: false, ... }
// }

isEnvironment(conditions: string[])

Check multiple conditions at once (AND logic):

// Check if mobile Safari on iOS
isEnvironment(['browser', 'mobile', 'safari', 'ios']); // true/false

// Check if desktop Chrome on Windows
isEnvironment(['desktop', 'chrome', 'windows']); // true/false

// Check if online PWA
isEnvironment(['pwa', 'online']); // true/false

checkFeatureSupport(features: string[])

Batch check multiple features:

const support = checkFeatureSupport(['webgl', 'canvas', 'webassembly']);
// { webgl: true, canvas: true, webassembly: true }

Usage Examples

Theme Detection and Application

import { isDarkMode, isLightMode, getColorScheme } from '@oxog/env-scout';

function applyTheme() {
  if (isDarkMode()) {
    document.body.classList.add('dark-theme');
  } else if (isLightMode()) {
    document.body.classList.add('light-theme');
  } else {
    // System has no preference
    document.body.classList.add('default-theme');
  }
}

Responsive Feature Loading

import { isMobile, isSlowConnection, checkFeatureSupport } from '@oxog/env-scout';

async function loadFeatures() {
  const features = checkFeatureSupport(['webgl', 'webassembly']);
  
  if (isMobile() || isSlowConnection()) {
    // Load lightweight version
    await import('./mobile-app');
  } else if (features.webgl && features.webassembly) {
    // Load full-featured version
    await import('./desktop-app');
  } else {
    // Load fallback version
    await import('./basic-app');
  }
}

Platform-Specific Code

import { isEnvironment, getOS } from '@oxog/env-scout';

function getPlatformSpecificPath() {
  if (isEnvironment(['electron', 'windows'])) {
    return 'C:\\Program Files\\MyApp';
  } else if (isEnvironment(['electron', 'macos'])) {
    return '/Applications/MyApp.app';
  } else if (isEnvironment(['node', 'linux'])) {
    return '/opt/myapp';
  }
  return './';
}

Analytics and Monitoring

import { getEnvironmentInfo, isBot } from '@oxog/env-scout';

function trackUser() {
  if (isBot()) {
    // Don't track bots
    return;
  }
  
  const env = getEnvironmentInfo();
  analytics.track('page_view', {
    runtime: env.runtime,
    browser: env.browser?.name,
    os: env.os,
    device: env.device.type,
    screen_size: `${env.screen.width}x${env.screen.height}`,
    connection: env.network.type
  });
}

Browser Usage via CDN

You can also use env-scout directly in the browser:

<script src="https://unpkg.com/@oxog/env-scout/dist/index.js"></script>
<script>
  const { isBrowser, getEnvironmentInfo } = window.EnvScout;
  
  if (isBrowser()) {
    console.log(getEnvironmentInfo());
  }
</script>

Tree-Shaking

The library is designed to be tree-shakeable. When you import specific functions, only the code for those functions will be included in your bundle:

// Only imports the isMobile function
import { isMobile } from '@oxog/env-scout';

// Only imports device-related functions
import { isMobile, isTablet, isDesktop } from '@oxog/env-scout/device';

Performance Considerations

• Detection results are cached automatically for 60 seconds to improve performance
• Functions use lazy evaluation where possible
• Feature detection is preferred over user agent parsing
• No external dependencies means faster load times

TypeScript Support

The library is written in TypeScript and provides comprehensive type definitions:

import type { EnvironmentInfo, BrowserInfo } from '@oxog/env-scout';

function processEnvironment(env: EnvironmentInfo) {
  // Full type safety
  console.log(env.browser?.name); // Type: string | undefined
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Ersin Koç

Links

• GitHub Repository
• NPM Package
• Bug Reports

Website

We now have a beautiful, modern website for EnvScout! 🎉

Live Website: https://env-scout.oxog.dev

Website Features

• Modern Design: Built with Tailwind CSS
• Fully Responsive: Works on all devices
• Interactive: Powered by Alpine.js
• Live Environment Detection: Real-time demo
• Complete Documentation: API reference and examples
• GitHub Integration: Direct links to repository and issues

Sections

1. Hero Section - Eye-catching introduction with live environment detection
2. Features - Showcase of library capabilities
3. API Reference - Complete function documentation
4. Code Examples - Real-world usage examples
5. Statistics - Version and dependency info
6. Call-to-Action - Quick installation guide

Local Development

To run the website locally:

cd website
python -m http.server 8000
# or
npx serve

Then open http://localhost:8000 in your browser.

Deployment

The website is automatically deployed to GitHub Pages from the main branch.

Domain: env-scout.oxog.dev

Recent Updates

Version 1.0.1 (December 15, 2025)

• ✅ Fixed 7 critical bugs in runtime detection
• ✅ Enhanced type safety with optional chaining
• ✅ Improved error handling for edge cases
• ✅ Replaced deprecated APIs
• ✅ Added comprehensive test suite
• ✅ Created modern website

What's Fixed

• isNode() - Added optional chaining for process.versions
• isBun() - Simplified optional chaining pattern
• isDeno() - Simplified optional chaining pattern
• isElectron() - Added optional chaining for process.versions
• isSharedWorker() - Added self null check
• isServiceWorker() - Added self null check
• isCordova() - Replaced deprecated document.URL

Made with ❤️ by Ersin Koç