JavaScript Global Identifiers Registry

Common errors

• TypeError: Cannot read properties of undefined (reading 'browser')

  cause The `globals` object was not correctly imported or required, or an attempt was made to access a non-existent environment key.
  fix Ensure `import globals from 'globals';` (ESM) or `const globals = require('globals');` (CJS) is present, and verify the environment key (e.g., `browser`, `node`) exists in the `globals` object. Consult `globals.json` for available keys.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in an ECMAScript module (ESM) context.
  fix If your project or file uses ESM (e.g., `"type": "module"` in `package.json` or `.mjs` files), use `import globals from 'globals';`. If you need to use CommonJS in an ESM project, consider dynamic `import()` or refactoring.

• ESLint not recognizing new globals or environments (e.g., `BigInt` or `process`)

  cause The `globals` package is either an outdated version, or ESLint's configuration is not correctly set up to use the `globals` package, especially with ESLint 9+.
  fix Update `globals` to the latest version (`npm install globals@latest`). For ESLint 9+, ensure `globals` is a direct `devDependency` and explicitly configured in your `eslint.config.js` or `.eslintrc.*` file under `languageOptions.globals` for the relevant environments (e.g., `globals.node`, `globals.browser`).

Warnings

• breaking In version 17.0.0, the `audioWorklet` environment was split from the `browser` environment. Code that previously relied on `globals.browser` to include `audioWorklet` specific globals will now need to explicitly reference `globals.audioWorklet`.
  Fix: If your linting or analysis tools require `audioWorklet` globals, update your configuration to include `globals.audioWorklet` explicitly or combine it with `globals.browser` as needed.
• breaking For ESLint version 9 and later, the `globals` package is no longer implicitly bundled by ESLint itself. Users must now include `globals` as a direct dependency in their project's `package.json`.
  Fix: Add `"globals": "^17.0.0"` to your `devDependencies` and ensure your ESLint configuration (e.g., in `eslint.config.js`) correctly references it, such as in `languageOptions.globals`.
• gotcha The boolean values associated with each global (`true` or `false`) indicate its writability (true for writable, false for read-only) as understood by static analysis tools. Misinterpreting `true` as merely 'exists' rather than 'is writable' can lead to incorrect linter configurations or unexpected behavior when enforcing coding standards.
  Fix: Always refer to the package documentation for the precise meaning of the boolean flags. Ensure your linting rules correctly leverage this distinction for read-only vs. writable globals.
• gotcha The package receives frequent updates to its global lists across various environments. While beneficial for staying current, this means specific global identifiers might be added, removed, or have their writability status changed between minor versions, which could subtly impact linting rules or code analysis if not accounted for.
  Fix: Regularly update the `globals` package (`npm update globals`) and review release notes for changes relevant to the environments you are targeting. Consider pinning minor versions if strict consistency of global definitions is critical.

Install

• npm install globals npm
• yarn add globals yarn
• pnpm add globals pnpm

Imports

• globals
  wrong:

  import { globals } from 'globals';

  correct:

  import globals from 'globals';

  The package exports a default object containing all environment globals. Named imports for the top-level 'globals' object are incorrect.
• globals
  wrong:

  const { globals } = require('globals');

  correct:

  const globals = require('globals');

  For CommonJS environments, `require` returns the full globals object. Destructuring the top-level 'globals' symbol is incorrect.
• globals.browser
  wrong:

  import { browser } from 'globals';

  correct:

  import globals from 'globals'; const browserGlobals = globals.browser;

  Environment-specific globals (e.g., `browser`, `node`) are properties of the default `globals` object, not direct named exports.

Quickstart

Demonstrates how to import the `globals` object and access environment-specific global identifiers, showing examples for browser and Node.js environments and how to inspect their writability status.

import globals from 'globals';

// Access all browser-specific globals
console.log('Browser globals example:');
console.log(Object.keys(globals.browser).slice(0, 5));
// Expected output: [ 'addEventListener', 'applicationCache', 'ArrayBuffer', 'atob', 'Audio' ]

// Access all Node.js built-in globals (excluding CommonJS module scope)
console.log('\nNode.js built-in globals example:');
console.log(Object.keys(globals.nodeBuiltin).slice(0, 5));
// Expected output: [ '__dirname', '__filename', 'Buffer', 'clearImmediate', 'clearInterval' ]

// Check if a specific global is read-only or writable (e.g., 'window' in browser)
console.log(`\n'window' is writable in browser: ${globals.browser.window}`);
// Expected output: 'window' is writable in browser: false (or true depending on exact env config)