Coralite Library

The Coralite library is used for processing and rendering HTML documents with custom elements, components, and plugins. It provides a structured way to manage document metadata, component paths, plugin configurations, and ignored attributes during rendering.

Table of Contents #

createCoralite Factory
Build Method
Save Method
Get Page Paths Using Custom Element
Add Render Queue
Create Component
Write File
Track Output File

createCoralite Factory #

Initializes a Coralite instance using the await createCoralite factory function. This replaces the legacy new Coralite() constructor.

Parameters #

Name	Type	Attribute	Description
options	`Object`	Required	Configuration options for the Coralite instance.
options.components	`string`	Required	The absolute or relative path to the directory containing Coralite components.
options.pages	`string`	Required	The absolute or relative path to the directory containing pages to be rendered.
options.plugins	`CoralitePluginInstance[]`	Optional	An array of plugin instances.
options.mode	`'production' \| 'development'`	Optional	Build mode. Defaults to `'production'`.
options.ignoreByAttribute	`IgnoreByAttribute[] \| string[]`	Optional	Attributes to ignore during processing.
options.skipRenderByAttribute	`IgnoreByAttribute[] \| string[]`	Optional	Attributes that trigger skipping element rendering.
options.onError	`CoraliteOnError`	Optional	A callback function for handling errors and warnings.

Example Usage #

  import { createCoralite } from 'coralite';
  
  const app = await createCoralite({
    components: './src/components',
    pages: './src/pages',
    mode: 'production',
    plugins: [myCustomPlugin]
  });

Build Method #

Compiles specified page(s) using the Three-Phase Sealed Queue architecture. It handles discovery, ISR invalidation, and parallel rendering.

  /**
   * Compiles specified page(s).
   *
   * @param {string | string[]} [path] - Path(s) to build. If omitted, builds all invalidated pages.
   * @param {CoraliteBuildOptions} [options] - Build configuration.
   * @param {function} [callback] - Optional per-page transform callback.
   * @return {Promise<coralitebuildresult[]>}
   */
  await app.build(path, options, callback)</coralitebuildresult[]>

Save Method #

Saves processed pages and generated client-side assets to the configured output directory.

  /**
   * Compiles and saves pages to disk.
   *
   * @param {string | string[]} [path] - Optional page path(s) to build.
   * @param {CoraliteBuildOptions} [options] - Build options.
   * @returns {Promise<coralitesaveresult[]>} Array of saved file results.
   */
  await app.save(path, options)</coralitesaveresult[]>

Get Page Paths Using Custom Element #

Uses the internal dependency graph to find all pages that consume a specific component.

  /**
   * @param {string} path - Component path or ID.
   * @returns {string[]} Page paths consuming this component.
   */
  app.getPagePathsUsingCustomElement(path)

Add Render Queue #

Adds a page (physical or virtual) to the current render queue. Virtual pages must be added during the onBeforeBuild hook.

  /**
   * @param {string | Object} value - Page path or virtual page object.
   * @param {string} buildId - The current build ID.
   */
  await app.addRenderQueue(value, buildId)

Create Component #

Imperatively creates a component element for inclusion in the AST.

  /**
   * @param {ComponentElementOptions} options
   * @returns {Promise<coraliteanynode | void>}
   */
  await app.createComponentElement(options)</coraliteanynode>

Write File #

Writes a file to the output directory and automatically registers it for the build cleanup whitelist. This is the recommended way for plugins to generate additional assets.

  /**
   * @param {string} dest - Relative path within the output directory.
   * @param {string | Buffer} content - The file content.
   * @param {object} [options] - Node.js writeFile options.
   * @returns {Promise<string>} The absolute path to the written file.
   */
  await app.writeFile(&apos;my-asset.json&apos;, JSON.stringify(data))</string>

Track Output File #

Manually registers a file path to be preserved during the build cleanup phase. This is useful for files generated by external tools or complex plugin logic that doesn't use app.writeFile.

  /**
   * @param {string} path - Absolute path to the file.
   */
  app.trackOutputFile(absolutePath)

Get Tracked Output Files #

Retrieves an array of all currently registered output file paths.

  /**
   * @returns {string[]}
   */
  app.getTrackedOutputFiles()