JavaScript Runtime and OS Environment Detector

1.1.0 · active · verified Sun Apr 19

The `environment` package provides a lightweight and robust utility for runtime detection of the JavaScript execution context. It allows developers to programmatically determine whether their code is running in a web browser, Node.js, Bun, Deno, Electron, jsdom, or various Web Worker environments (dedicated, shared, service). Additionally, it offers checks for common operating systems like macOS, Windows, Linux, iOS, and Android, introduced in version 1.1.0. The current stable version is 1.1.0, with a conservative release cadence that suggests stability. Its primary differentiator is its comprehensive and accurate detection logic for a wide array of JavaScript runtimes and host environments, making it useful for environment-specific configurations or feature toggles, though the documentation encourages preferring conditional exports and imports where possible for better optimization.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use `import` statements from this ESM-only package within a CommonJS-only Node.js project or script.

fix Add `"type": "module"` to your `package.json` file or rename your script file to have a `.mjs` extension. Ensure your Node.js version is compatible with ES Modules (Node.js 12+ for basic support, 14+ recommended).
```
TypeError: (0 , environment_1.isBrowser) is not a function
```
cause This error typically occurs in TypeScript projects when the `tsconfig.json` `module` option is set to a CommonJS target (e.g., `"commonjs"`) but the source code is trying to import an ESM package directly without proper interop or bundling.

fix Adjust your `tsconfig.json` to target a modern module system like `"ESNext"` or `"NodeNext"`, or configure your bundler (e.g., Webpack, Rollup, esbuild) to correctly handle ESM imports and transpile them for your target environment. Ensure named imports are correctly destructured, e.g., `import { isBrowser } from 'environment';`.

Warnings

gotcha Over-reliance on runtime checks can lead to less optimized bundles and slower cold starts. The official documentation recommends preferring conditional package exports (via `package.json` `exports` field) and imports for environment-specific code splitting where possible.
Fix: Refactor code to leverage `package.json` `exports` field for environment-specific entry points (e.g., `browser`, `node` conditions) or use bundler-specific environment variables for dead code elimination at build time.
breaking This package is exclusively an ES Module (ESM) and does not provide a CommonJS (CJS) entry point. Attempting to `require()` the package or use `import` statements in a CJS context will result in a runtime error.
Fix: Ensure your `package.json` contains `"type": "module"` or rename your script files to `.mjs` to enable ESM. Convert any `require()` calls to `import` statements. If targeting older Node.js versions or CJS environments strictly, consider transpiling with a bundler or using a different package.

Install

npm install environment npm
yarn add environment yarn
pnpm add environment pnpm

Imports

isBrowser
wrong:
```
const { isBrowser } = require('environment');
```
correct:
```
import { isBrowser } from 'environment';
```
This package is ESM-only (ES Modules) since v1.0.0. Ensure your project is configured for ES modules to use named imports.

isNode

wrong:

import environment from 'environment'; environment.isNode;

correct:

import { isNode } from 'environment';

There is no default export; all checks are exposed as named exports.

isMacOs

wrong:

import * as environment from 'environment'; environment.isMacOs;

correct:

import { isMacOs, isWindows } from 'environment';

Destructuring named imports directly is the recommended practice for optimal tree-shaking.

Quickstart

Demonstrates how to use various named exports (e.g., `isBrowser`, `isNode`, `isMacOs`) to detect the current JavaScript runtime and operating system at execution time.

import { isBrowser, isNode, isBun, isMacOs, isWindows, isLinux } from 'environment';

function displayEnvironmentInfo() {
  console.log('Checking current environment...');

  if (isBrowser) {
    console.log('Detected: Web Browser environment.');
  } else if (isNode) {
    console.log('Detected: Node.js environment.');
  } else if (isBun) {
    console.log('Detected: Bun runtime environment.');
  } else {
    console.log('Detected: Unknown or unsupported JavaScript runtime.');
  }

  console.log('Checking operating system...');
  if (isMacOs) {
    console.log('Running on: macOS operating system.');
  } else if (isWindows) {
    console.log('Running on: Windows operating system.');
  } else if (isLinux) {
    console.log('Running on: Linux operating system.');
  } else {
    console.log('Running on: Another operating system or OS not detectable.');
  }
}

disEnvironmentInfo();

view raw JSON →