Coralite v0.30.0 Released

Thomas David - 8 Apr 26

Coralite v0.30.0 is now available. This release stabilizes the framework runtime by introducing a unified error-handling system, replacing the global, document-wide MutationObserver with efficient eager component mapping, and addressing nested declarative elements inside shadow DOM boundaries. It also improves application startup times and implements stricter API boundaries for web component state mutation.

This release introduces a framework-wide onError structured callback mechanism. It unifies diagnostic reporting across the HTML parser, style transformation pipelines, build error-handling flows, and developer CLI tools. An internal handleError method safely wraps the user-configured callback, ensuring that errors are safely caught, formatted, and exposed without revealing internal handler implementation details. By default, the logger automatically throws when encountering critical errors (level 'ERR'), enabling reliable CI failure detection.

  // coralite.config.js
  export default {
    onError(error) {
      if (error.level === 'ERR') {
        console.error(`[Coralite Critical] Code ${error.code}: ${error.message}`);
      } else {
        console.warn(`[Coralite Warning] ${error.message}`);
      }
    }
  };

To improve browser rendering performance and eliminate event loop overhead, the global MutationObserver injected into generated pages has been removed. In its place, Coralite now eagerly pre-maps page dependencies. Component script modules serialize child declarative dependencies inside a dependencies manifest, and components query elements directly during execution. An internal loadCache guards against duplicate module network requests and race conditions.

Furthermore, this update adds recursive component instantiation inside imperative web components. A dedicated helper recursively loads components and registers shadow-root-level observers, ensuring declarative child components dynamically inserted into a shadow DOM are automatically processed and hydrated.

Framework boot and compile times have been optimized through several structural updates:

• Lazy Component Loading: The createPlugin method now registers and loads component files lazily, preventing synchronous I/O bottlenecks.
• Parallel Recursive Scanner: The file scanner (getHtmlFiles) has been refactored to query directories recursively using parallel filesystem requests.
• Parallel Registration: Initialization processes inside Coralite.prototype.initialise now execute in parallel, maximizing node event loop utilization.

• Private Web Component Values Property: The internal this.values property inside the generated ComponentElement base class has been renamed to this._values. Consumers must now pass state via standard HTML attributes (e.g., element.setAttribute(...)) instead of directly mutating internal properties, ensuring standard DOM compliance.

  // Before v0.30.0 (direct property mutation)
  myElement.values.someState = 'new-value';
  
  // In v0.30.0 (standard DOM interaction)
  myElement.setAttribute('some-state', 'new-value');

To upgrade to the latest version, update your project dependencies:

  npm install coralite@0.30.0

  npm install coralite-scripts@0.30.0