Detect Bundler Environment

1.1.0 · active · verified Tue Apr 21

The `detect-bundler` package provides build-time flags to identify if the current code is being bundled for a web browser (e.g., via Webpack, Browserify) or for React Native (via Metro). Unlike runtime environment detection, this library leverages the `package.json` `browser` field specification to resolve platform-specific code paths during the build process, ensuring zero runtime overhead. Its current stable version is 1.1.0. Given its focused utility, new releases are infrequent and primarily address minor updates or compatibility fixes rather than new features. This design choice makes it particularly useful for libraries or applications needing to conditionally include platform-specific logic without impacting runtime performance, differentiating it from solutions that rely on `navigator` or `process` checks.

Common errors

```
ReferenceError: window is not defined
```
cause Code relying on `isBrowser` being true attempts to access browser-specific globals in a non-browser build target where `detect-bundler` resolved `isBrowser` to `false`.

fix Ensure that code paths guarded by `isBrowser` or `isReactNative` are truly only executed or imported when the respective flag is statically true for the current build target. This may involve proper bundler configuration for conditional exports or environment targets.
```
console.log(isBrowser) always shows 'false' (or 'true') even though I expect the opposite!
```
cause Misunderstanding that the `isBrowser` and `isReactNative` flags are resolved *at build time* based on bundler configuration and `package.json`'s `browser` field, not detected dynamically at runtime.

fix Verify your bundler configuration (e.g., Webpack `target`, Metro configuration) and how it interprets the `package.json` `browser` field. If `isBrowser` is unexpectedly `false`, your bundler might be resolving to the Node.js version of the package, even if the eventual target is a browser.

Warnings

gotcha The `detect-bundler` flags (`isBrowser`, `isReactNative`) are resolved exclusively at *build time* by your bundler based on the `package.json` `browser` field. They are not dynamic runtime checks. Assuming they will change or reflect the environment at runtime will lead to incorrect behavior.
Fix: Understand that these flags become static boolean constants in your bundled output. Use them for conditional imports or code paths that are resolved *before* your application runs, not for runtime environment switching. For runtime detection, use standard browser APIs (e.g., `window` object) or Node.js `process` globals.

Install

npm install detect-bundler npm
yarn add detect-bundler yarn
pnpm add detect-bundler pnpm

Imports

isBrowser
wrong:
```
const isBrowser = require('detect-bundler').isBrowser;
```
correct:
```
import { isBrowser } from 'detect-bundler';
```
ESM is the recommended import style; CommonJS require() is also supported but less idiomatic for modern TypeScript projects.
isReactNative
wrong:
```
const isReactNative = require('detect-bundler').isReactNative;
```
correct:
```
import { isReactNative } from 'detect-bundler';
```
Flags are resolved at build-time based on package.json 'browser' field, not at runtime.

{ isBrowser, isReactNative }

wrong:

import detectBundler from 'detect-bundler';

correct:

import { isBrowser, isReactNative } from 'detect-bundler';

The package exports named flags, not a default export.

Quickstart

Demonstrates importing and using the `isBrowser` and `isReactNative` flags to conditionally execute platform-specific code at build time.

import { isBrowser, isReactNative } from 'detect-bundler';

// This code demonstrates how to use the build-time detection flags.
// The values of isBrowser and isReactNative are determined by your bundler
// and package.json 'browser' field configuration at build-time.
// They are static constants in the final bundled output.

if (isBrowser) {
  console.log('Running in a browser environment (detected at build time).');
  // Perform browser-specific initialization, e.g., accessing DOM
  // document.body.classList.add('is-browser');
} else if (isReactNative) {
  console.log('Running in a React Native environment (detected at build time).');
  // Perform React Native-specific initialization
  // import { Platform } from 'react-native';
  // if (Platform.OS === 'ios') { /* ... */ }
} else {
  console.log('Running in a Node.js-like or other environment.');
  // Perform Node.js or universal initialization
  console.log(`Current environment variable example: ${process.env.NODE_ENV ?? 'undefined'}`);
}

// Example of conditional export based on detection
export const platformSpecificMessage = isBrowser
  ? 'Hello from the Web!'
  : isReactNative
    ? 'Hello from React Native!'
    : 'Hello from Node.js!';

console.log(platformSpecificMessage);

view raw JSON →