Resolving ESLint Not Defined 'HTMLElement' and 'customElements' in JavaScript Projects (Non-TypeScript)

Understanding ESLint Errors in JavaScript Web Components

When working with web components in JavaScript, you may encounter ESLint errors like 'HTMLElement is not defined' or 'customElements is not defined'. These issues typically arise from ESLint's rule enforcement, but can be confusing, especially when they seem to target code that's working fine in the browser. These errors are not related to TypeScript, yet some solutions focus on TypeScript-specific setups.

In purely JavaScript projects, especially those that do not involve TypeScript, developers may struggle to find relevant fixes for such issues. The default ESLint configuration assumes the global availability of certain objects or frameworks. As a result, simple tasks like creating web components or using test frameworks like suite and test can trigger unnecessary ESLint errors.

The problem arises because ESLint doesn't recognize that certain features, like HTMLElement or customElements, are available in the browser but are not explicitly defined in the current environment. Understanding how to adjust your ESLint configuration will prevent these false-positive errors and streamline your development workflow.

In this article, we will explore how to modify your ESLint configuration to allow references to HTMLElement, customElements, and testing functions like suite and test. By applying these tweaks, you'll be able to code web components smoothly without constant interruptions from ESLint.

Solving ESLint Errors in JavaScript Projects Using Web Components

The scripts provided above are designed to address common issues developers face when building web components using plain JavaScript, particularly the 'HTMLElement is not defined' and 'customElements is not defined' errors in ESLint. The core problem is that ESLint treats these as undefined because they are not declared in the current runtime environment. To resolve this, we customized the ESLint configuration to recognize browser-specific globals such as HTMLElement and customElements. This involves adjusting the no-undef rule to prevent ESLint from flagging these globals as undefined. Additionally, we ensured that testing frameworks like Mocha, which uses suite and test, are accounted for in the configuration.

The script for the HelloWorldComponent demonstrates a typical use case for custom elements. It defines a custom web component by extending HTMLElement and specifying a set of lifecycle methods. The key method, connectedCallback, is triggered when the component is added to the DOM, allowing us to update the element's content dynamically. Another important method, attributeChangedCallback, responds to changes in the component's attributes. This method is crucial for making the component reactive to changes in its properties, like the 'name' attribute, which is observed by the component. The customElements.define method registers the component with the browser, linking the tag to the HelloWorldComponent class.

For testing, the script uses the Open WC testing framework to ensure the web component behaves as expected. The fixture utility instantiates the component in a controlled environment, simulating how it would function in the browser. We then use assertions with expect to verify that the component is created successfully and that its content matches the expected output. The inclusion of tests helps ensure the component's reliability and catches any potential issues early in the development process. The Mocha framework’s suite and test functions organize the test cases and make it easier to isolate and diagnose specific features.

By following the provided solutions, developers can avoid common ESLint issues while working with browser APIs and web components. The scripts also emphasize best practices, such as modular code and comprehensive testing, which are essential for maintaining clean, efficient, and reliable JavaScript applications. Ensuring ESLint is correctly configured allows for smoother development, as it reduces unnecessary errors, letting you focus on building robust features without being blocked by tooling issues. Overall, these examples provide a complete and reusable approach to managing ESLint and JavaScript web components.

/* eslint.config.js */
import eslint from "@eslint/js";
export default [
  { files: ["/*.js", "/*.cjs", "/*.mjs"], 
    rules: {
      ...eslint.configs.recommended.rules,
      "no-undef": ["error", { "typeof": true }] 
    } },
  { ignores: ["rollup.config.js", "web-test-runner.config.js"] } 
];
// This configuration tells ESLint to allow certain browser globals

/* eslint.config.js */
export default [
  { files: ["/*.js"], 
    env: { browser: true, es2021: true, mocha: true },
    globals: { HTMLElement: "readonly", customElements: "readonly" },
    rules: { "no-undef": "off" } },
  { ignores: ["rollup.config.js", "web-test-runner.config.js"] } 
];
// This configuration disables the 'no-undef' rule for test functions.

/* src/hello-world.component.js */
export class HelloWorldComponent extends HTMLElement {
  static get observedAttributes() { return ["name"]; }
  constructor() {
    super();
    this.name = "World";
  }
  connectedCallback() {
    this.textContent = `Hello ${this.name}!`;
  }
  attributeChangedCallback(attr, oldVal, newVal) {
    if (oldVal === newVal) return;
    switch (attr) {
      case "name":
        this.name = newVal;
        break;
      default:
        console.error("Unhandled attribute:", attr);
    }
  }
}
customElements.define("hello-world", HelloWorldComponent);
// Defines a 'hello-world' custom element with optimized error handling

/* src/hello-world.component.spec.js */
import { expect, fixture, html } from "@open-wc/testing";
suite("hello-world.component tests", () => {
  test("fixture instantiation", async () => {
    const el = await fixture(html`<hello-world></hello-world>`);
    expect(el).not.to.equal(null);
    expect(el.textContent).to.equal("Hello World!");
  });
});
// This test checks that the hello-world component is instantiated properly

Improving Web Component Development with Custom ESLint Configuration

When building custom elements in pure JavaScript, developers often encounter issues like ESLint flagging browser-specific APIs as undefined. These issues are particularly noticeable when using features like customElements or HTMLElement, which are not recognized by ESLint’s default configuration. Although these APIs work flawlessly in the browser, ESLint requires additional configuration to acknowledge their existence. This can slow down your development process and make your code look error-ridden when, in fact, everything works as expected in the runtime environment.

Another important consideration is testing. Many JavaScript projects use frameworks like Mocha or Open WC, which introduce global functions such as suite and test. These are also flagged by ESLint unless it is configured to recognize them. Instead of disabling no-undef entirely, a better practice is to customize ESLint to allow these test-related globals only where appropriate, thus ensuring the rest of your code remains protected from undefined variable errors. This helps in maintaining clean, efficient, and reliable JavaScript codebases, particularly in large projects where testing is essential.

For developers, adjusting ESLint configurations isn’t just about resolving these immediate issues. It’s about creating a scalable and reusable development setup that can be easily extended. With modular ESLint configurations, you can define which parts of your project need access to browser globals and which need testing-specific configurations. This modularity enhances performance and security by ensuring that only the necessary parts of your project have access to certain features, reducing the risk of unintended errors or security vulnerabilities.