or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-lrnwebcomponents--deduping-fix

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@lrnwebcomponents/deduping-fix@8.0.x

To install, run

npx @tessl/cli install tessl/npm-lrnwebcomponents--deduping-fix@8.0.0

index.mddocs/

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;
}