CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-lrnwebcomponents--deduping-fix

A utility that prevents duplicate custom element registration errors by monkey-patching window.customElements.define

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Deduping Fix

Deduping Fix is a utility package that solves a critical web components platform issue where attempting to define the same custom element twice causes a hard failure. The package provides a non-breaking solution by monkey-patching the global window.customElements.define function to check for existing element definitions before attempting registration.

Package Information

  • Package Name: @lrnwebcomponents/deduping-fix
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @lrnwebcomponents/deduping-fix

Core Imports

import '@lrnwebcomponents/deduping-fix';

For CommonJS environments:

require('@lrnwebcomponents/deduping-fix');

Basic Usage

The package works entirely through side effects when imported. No explicit API calls are needed:

import '@lrnwebcomponents/deduping-fix';

// Now safe to define custom elements multiple times
customElements.define('my-element', class extends HTMLElement {
  // Element implementation
});

// This won't throw an error, just logs a warning
customElements.define('my-element', class extends HTMLElement {
  // Different implementation - will be ignored with warning
});

Architecture

Deduping Fix works by intercepting the native Custom Elements API:

  • Global Modification: Replaces window.customElements.define with a wrapper function
  • Duplicate Detection: Uses customElements.get() to check for existing definitions
  • Graceful Degradation: Issues console warnings instead of throwing exceptions
  • Transparent Operation: Maintains the original API contract for new element definitions

Capabilities

Custom Element Definition Protection

Prevents duplicate custom element registration errors by intercepting and modifying the global customElements.define function.

/**
 * Modified window.customElements.define function that prevents duplicate registrations
 * @param name - The name of the custom element to define
 * @param cl - The custom element constructor class  
 * @param conf - Optional configuration object for the custom element
 */
window.customElements.define(
  name: string, 
  cl: CustomElementConstructor, 
  conf?: ElementDefinitionOptions
): void;

Behavior Changes:

  • Before import: Duplicate element definitions throw DOMException: "Failed to execute 'define' on 'CustomElementRegistry'"
  • After import: Duplicate element definitions log console.warn("${name} has been defined twice") and continue execution

Usage Examples:

import '@lrnwebcomponents/deduping-fix';

// First definition - works normally
customElements.define('my-button', class MyButton extends HTMLElement {
  constructor() {
    super();
    this.innerHTML = '<button>Click me</button>';
  }
});

// Second definition - logs warning instead of throwing error
customElements.define('my-button', class AnotherButton extends HTMLElement {
  constructor() {
    super();
    this.innerHTML = '<button>Different button</button>';
  }
});
// Console output: "my-button has been defined twice"

Common Use Cases:

// Development hot-reloading scenarios
import '@lrnwebcomponents/deduping-fix';
import './my-component.js'; // May be reloaded multiple times

// Dynamic imports with timing issues
import '@lrnwebcomponents/deduping-fix';
Promise.all([
  import('./component-a.js'),
  import('./component-b.js'), // Both might define same element
]).then(() => {
  // No registration conflicts
});

// Legacy platform integration
import '@lrnwebcomponents/deduping-fix';
// Import multiple libraries that might define conflicting elements
import 'legacy-component-library-1';
import 'legacy-component-library-2';

Error Handling

The package handles duplicate custom element definitions gracefully:

  • No exceptions thrown: Prevents application crashes from duplicate definitions
  • Console warnings: Provides visibility into duplicate registration attempts
  • Original behavior preserved: New element definitions work exactly as before
  • Platform compatibility: Works with all browsers supporting Custom Elements v1

Browser Compatibility

  • Modern Browsers: Chrome 54+, Firefox 63+, Safari 10.1+, Edge 79+
  • Requirements: Native Custom Elements v1 support
  • Node.js: Not applicable (requires browser window object)
  • Module System: ES Modules only

Types

/**
 * Original customElements.define function reference stored before modification
 */
declare const _customElementsDefine: (
  name: string,
  constructor: CustomElementConstructor,
  options?: ElementDefinitionOptions
) => void;

/**
 * Standard Custom Elements API types
 */
interface CustomElementConstructor {
  new (): HTMLElement;
}

interface ElementDefinitionOptions {
  extends?: string;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@lrnwebcomponents/deduping-fix@8.0.x
Publish Source
CLI
Badge
tessl/npm-lrnwebcomponents--deduping-fix badge