Coralite v0.29.0 Released

Thomas David - 23 Mar 26

Coralite v0.29.0 is now available. This release refines the core architecture by completely removing standalone components in favor of a unified, hybrid declarative/imperative web component model. In addition, this version introduces recursive imperative component dependency resolution, refactors the plugin client helpers to a more efficient two-phase execution cycle, refines the hydration mechanism around the ref attribute, and cleans up framework terminology by renaming all "Document" types to "Component".

In previous versions, Coralite maintained a distinct configuration and output format for standalone components. To simplify the codebase and improve performance, standalone components have been entirely removed. In their place, Coralite now standardizes on a hybrid declarative and imperative web component model. The standaloneOutput configuration has been removed from the Core API, types, and CLI, and the compilation logic has been simplified accordingly.

As part of this model, the client.script context properties have been updated to replace the old document property with root. This property can dynamically point to either a ShadowRoot (for encapsulated shadow DOM elements) or a Document fragment, providing a cleaner abstraction for scripting component behavior.

  // Before:
  export default ({ document }) => {
    const element = document.getElementById('my-el');
  };
  
  // After:
  export default ({ root }) => {
    // 'root' is either a ShadowRoot or a Document fragment
    const element = root.querySelector('[ref="my-el"]');
  };

To support advanced imperative workflows, Coralite v0.29.0 implements recursive dependency resolution and bundling for imperative web components. Authors can define a new client.components array inside client scripts to specify string dependencies representing other imperative web components. These are recursively resolved via a shared functions registry to prevent infinite loops and ensure all nested components and their scoped styles are bundled correctly prior to registration.

  // Declaring dependencies in a component's client script
  export const components = ['coralite-button', 'coralite-icon'];
  
  export default ({ root, components }) => {
    // Subcomponents are automatically loaded and bundled before this component registers
  };

Plugin helpers registered via defineComponent now run in a two-phase execution cycle: globalContext => localContext. Previously, helpers were executed in a single phase, which meant that heavy objects like imports and config were repeatedly injected and processed during every instance render. With two-phase execution, the initial global phase receives the global configuration and imports once, returning a closure that is executed per component instance with local context variables (such as root and refs).

  // Two-phase plugin client helper structure
  export default (globalContext) => {
    // Phase 1: Global setup (e.g., config, imports) executed once
    const { imports, config } = globalContext;
  
    return (localContext) => {
      // Phase 2: Local execution executed per component instance
      const { root, refs } = localContext;
    };
  };

To prevent conflicts and simplify DOM queries, the hydration engine no longer deletes the ref attribute and sets the id attribute. Instead, the framework modifies the ref attribute directly with a unique value and preserves it. The refs plugin has been updated to query matching elements using querySelector('[ref="..."]') instead of getElementById, maintaining high performance through query caching logic.

To better align terminology with modern web standards, Coralite has renamed all instances of "Document" types to "Component" across the codebase. This represents a clean break from old naming conventions and makes the internal APIs more intuitive.

• CoraliteDocument is now CoraliteComponent
• CoraliteDocumentRoot is now CoraliteComponentRoot
• CoraliteDocumentResult is now CoraliteComponentResult
• CoraliteDocumentValues is now CoraliteComponentValues
• cloneDocumentInstance is now cloneComponentInstance

• Method Rename: Coralite.prototype.createComponent has been renamed to Coralite.prototype.createComponentElement.
• Context Property Replacement: Inside client.script, the document property has been replaced by root (which yields either the ShadowRoot or Document context).
• Standalone Components Removal: The standaloneOutput configuration and --standalone CLI flags have been completely removed.
• Plugin Helper API: Client helpers now must adhere to the two-phase currying signature (globalContext => localContext).

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

  npm install coralite@0.29.0

  npm install coralite-scripts@0.29.0