Comprehensive Guide to Global Variable Configuration in ESLint: From package.json to Environment Settings

Problem Background and Core Challenges

In modern JavaScript development, ESLint has become a standard tool for ensuring code quality. However, when code runs in a browser environment and accesses global objects like window, developers often encounter the "window" is not defined warning. This is not a code error but rather ESLint's static analysis being unable to automatically recognize global variables in the runtime environment. Using window as an example, this article systematically explains how to resolve such issues through configuration.

Direct Configuration in package.json

According to community best practices, the most straightforward solution is to add an eslintConfig field in the package.json file. The specific configuration is as follows:

"eslintConfig": {
  "globals": {
    "window": true
  }
}

This configuration explicitly informs ESLint that window is a defined global variable, with true indicating it is readable and writable. The advantage of this method lies in its centralized configuration and seamless integration with project dependency management, making it particularly suitable for small projects or rapid prototyping that do not require complex environment setups.

Alternative Approach: Environment Configuration

In addition to directly declaring global variables, ESLint also supports defining them in batches through environment configuration. For browser environments, the built-in browser environment can be used:

"env": {
  "browser": true,
  "node": true
}

Enabling browser: true allows ESLint to automatically recognize all browser global variables, including window, document, and navigator. This method aligns better with semantic configuration principles, as it eliminates the need to declare each variable individually when the project explicitly runs in a browser.

Configuration Priority and Combined Usage

In real-world projects, both configuration methods can be combined. ESLint configurations follow merging rules: settings in .eslintrc.* files override those in eslintConfig within package.json. When using both, it is advisable to adhere to the following principles:

• For project-level common environments (e.g., browser, Node.js), configure env in .eslintrc.json
• For project-specific custom global variables, declare them in eslintConfig.globals in package.json
• Avoid duplicate declarations to prevent configuration conflicts

Practical Examples and Considerations

Consider a frontend project that uses both browser APIs and third-party library global variables. A complete configuration example is as follows:

// package.json
{
  "eslintConfig": {
    "globals": {
      "myCustomGlobal": true
    }
  }
}

// .eslintrc.json
{
  "env": {
    "browser": true
  },
  "rules": {
    "no-undef": "error"
  }
}

This configuration ensures ESLint correctly recognizes window (via the browser environment) and the custom global variable myCustomGlobal. Note that variables declared in globals override同名 definitions in environment variables, so developers should ensure such overrides align with expectations.

Conclusion and Best Practice Recommendations

The core of handling ESLint global variable warnings lies in accurately describing the code runtime environment. For pure browser projects, prioritize using env: { browser: true }; for mixed environments or scenarios requiring special global variable declarations, combine it with eslintConfig.globals. Configurations should maintain simplicity and maintainability, avoiding over-declaration that could disable ESLint's undefined checking functionality. Through reasonable configuration, developers can benefit from ESLint's code quality assurance while preventing false positives for legitimate global variable usage.