{"id":15588,"library":"detect-bundler","title":"Detect Bundler Environment","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","build","bundler","detect","platform","typescript"],"install":[{"cmd":"npm install detect-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add detect-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add detect-bundler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM is the recommended import style; CommonJS require() is also supported but less idiomatic for modern TypeScript projects.","wrong":"const isBrowser = require('detect-bundler').isBrowser;","symbol":"isBrowser","correct":"import { isBrowser } from 'detect-bundler';"},{"note":"Flags are resolved at build-time based on package.json 'browser' field, not at runtime.","wrong":"const isReactNative = require('detect-bundler').isReactNative;","symbol":"isReactNative","correct":"import { isReactNative } from 'detect-bundler';"},{"note":"The package exports named flags, not a default export.","wrong":"import detectBundler from 'detect-bundler';","symbol":"{ isBrowser, isReactNative }","correct":"import { isBrowser, isReactNative } from 'detect-bundler';"}],"quickstart":{"code":"import { isBrowser, isReactNative } from 'detect-bundler';\n\n// This code demonstrates how to use the build-time detection flags.\n// The values of isBrowser and isReactNative are determined by your bundler\n// and package.json 'browser' field configuration at build-time.\n// They are static constants in the final bundled output.\n\nif (isBrowser) {\n  console.log('Running in a browser environment (detected at build time).');\n  // Perform browser-specific initialization, e.g., accessing DOM\n  // document.body.classList.add('is-browser');\n} else if (isReactNative) {\n  console.log('Running in a React Native environment (detected at build time).');\n  // Perform React Native-specific initialization\n  // import { Platform } from 'react-native';\n  // if (Platform.OS === 'ios') { /* ... */ }\n} else {\n  console.log('Running in a Node.js-like or other environment.');\n  // Perform Node.js or universal initialization\n  console.log(`Current environment variable example: ${process.env.NODE_ENV ?? 'undefined'}`);\n}\n\n// Example of conditional export based on detection\nexport const platformSpecificMessage = isBrowser\n  ? 'Hello from the Web!'\n  : isReactNative\n    ? 'Hello from React Native!'\n    : 'Hello from Node.js!';\n\nconsole.log(platformSpecificMessage);","lang":"typescript","description":"Demonstrates importing and using the `isBrowser` and `isReactNative` flags to conditionally execute platform-specific code at build time."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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`.","error":"ReferenceError: window is not defined"},{"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.","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.","error":"console.log(isBrowser) always shows 'false' (or 'true') even though I expect the opposite!"}],"ecosystem":"npm"}