@jsdevtools/host-environment

Host Environment

Easily detect what host environment your code is running in

Host Environment is a universal JavaScript library that makes it easy to detect what host environment your code is running in. It lets you answer questions like:

• Am I running in Node.js or a web browser?
• Is this Node 8.x or newer?
• Are we in Internet Explorer?
• Is this a Windows computer?
• Are we running in a CI/CD environment?

Maybe some parts of your app are only available in Node and not in web browsers. Or maybe you need to determine whether to load a polyfill library. Or maybe you need to conditionally run tests in different environments. Whatever your reason, Host Environment can help.

Example

import host from "@jsdevtools/host-environment";

if (host.browser) {
  // Browser logic here

  if (host.browser.IE) {
    // Load a polyfill for Internet Explorer
  }
}

if (host.node) {
  // Node.js logic here

  if (host.node.version < 8) {
    // Load a polyfill for older versions of Node
  }

  if (host.os.windows) {
    // Windows-specific logic here
  }
}

Related Projects

• karma-host-environment
  Access environment variables and other system info in your browser tests.

Installation

Install using npm:

npm install @jsdevtools/host-environment

Usage

When using Host Environment in Node.js apps, you'll probably want to use CommonJS syntax:

const host = require("@jsdevtools/host-environment");

When using a transpiler such as Babel or TypeScript, or a bundler such as Webpack or Rollup, you can use ECMAScript modules syntax instead:

import host from "@jsdevtools/host-environment";

Browser support

Host Environment supports recent versions of every major web browser. Older browsers may require Babel and/or polyfills.

To use Host Environment in a browser, you'll need to use a bundling tool such as Webpack, Rollup, Parcel, or Browserify. Some bundlers may require a bit of configuration, such as setting browser: true in rollup-plugin-resolve.

API

host.global

When running in a web browser, host.global is a reference to the window object. When running in Node.js, it's a reference to the global object.

host.path

The path of the host process, as a string. When running in Node.js, this is set to process.execPath. When running in a web browser, it is the URL of the web page (window.location.href).

host.url

The same as host.path, but as a parsed URL object. When running in Node.js, this will be a file:// URL.

host.cwd

The current working directory, as a string. When running in Node.js, this is set to process.cwd. When running in a web browser, it is the parent directory of the current web page

host.cwdURL

The same as host.cwd, but as a parsed URL object. When running in Node.js, this will be a file:// URL.

host.os

This property is an object with the following structure:

{
  windows: false,       // Windows or Windows Phone
  mac: true,            // Mac OS or iOS
  linux: false          // Linux, Android, or other *nix platforms
}

Note: Only one of the properties will be true. All others are false.

host.env

This property is an object containing environment variables as key/value strings. When running in Node.js, it is set to process.env.

When running in a web browser, it is usually an empty object, since web browsers don't have access to environment variables. However, when paired with tools like karma-host-environment, it's possible to work-around this limitation and allow you to access environment variables in the browser.

{
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/bash',
  USER: 'maciej',
  PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
  PWD: '/Users/maciej',
  EDITOR: 'vim',
  SHLVL: '1',
  HOME: '/Users/maciej',
  LOGNAME: 'maciej',
  _: '/usr/local/bin/node'
}

host.ci

When running on a known CI/CD host, this property is an object containing informaation about the CI/CD host and the job that's being run.

When running outside of a CI/CD host, this property is false. Since CI/CD hosts are detected based on the presence of environment variables, this property will usually be false when running in a web browser (where environment variables aren't accessible). However, when paired with tools like karma-host-environment, it's possible to work-around this limitation and allow you to access CI/CD information in the browser.

{
  name: "Travis CI",    // The name of the CI/CD host
  TRAVIS: true,         // The CI/CD host as a boolean
  pr: true,             // Whether the CI/CD job was triggered by a pull-request
}

host.node

This property is false when running in a web browser. When running in Node.js it is an object with the following structure:

{
  v7: true,             // The major version, as a boolean
  version: 7.3,         // The major.minor version, as a float
  majorVersion: 7,      // The major version, as an integer
  minorVersion: 3,      // The minor version, as an integer
  patchVersion: 24      // The patch version, as an integer
}

host.browser

This property is false when running in Node.js. When running in a browser it is an object with the following structure:

{
  chrome: {             // false if not Chrome
    v58: true,          // The major version, as a boolean
    version: 58.4,      // The major.minor version, as a float
    majorVersion: 58,   // The major version, as an integer
    minorVersion: 4,    // The minor version, as an integer
    patchVersion: 3029, // The patch version, as an integer
    mobile: false,      // true on mobile
  },
  firefox: false,       // An object like above if running in Firefox
  safari: false,        // An object like above if running in Safari
  edge: false,          // An object like above if running in Edge
  IE: false,            // An object like above if running in Internet Explorer
  mobile: false,        // true for any mobile browser (iOS, Android, Windows Phone, etc)
}

Note: Only one of the browser properties will be an object. All others are false.

Contributing

Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.

Building

To build the project locally on your computer:

• Clone this repo
  git clone https://github.com/JS-DevTools/host-environment.git

• Install dependencies
  npm install

• Build the code
  npm run build

• Run the tests
  npm test

License

Host Environment is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤