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
Content Security Policy Utilities
Content Security Policy Build Results
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.
options.csp	`CoraliteCSPConfig`	Optional	Content Security Policy options for SSG hashing, SSR nonces, and script/style externalization.

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[]>

Content Security Policy Utilities #

Coralite exports low-level CSP helper functions for custom server integrations and middleware pipelines.

calculateHash(content, algorithm) #

Calculates a cryptographic base64 hash string suitable for CSP header source lists.

  import { calculateHash } from 'coralite';
  
  // Returns: "'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='"
  const hash = calculateHash('console.log("hello");', 'sha256');

formatCSPDirectives(directives, options) #

Converts a directive dictionary into a normalized Content-Security-Policy HTTP header string.

  import { formatCSPDirectives } from 'coralite';
  
  const headerString = formatCSPDirectives({
    'default-src': ["'self'"],
    'script-src': ["'self'", "'sha256-abc...'"]
  });

injectCSPMeta(root, head, cspContent, reportOnly) #

Helper used during AST compilation to insert or update the <meta http-equiv="Content-Security-Policy"> element in the document <head>.

Content Security Policy Build Results #

When rendering or compiling pages via app.build() or app.save(), each returned page result object exposes a csp property (type CoraliteCSPResult):

  const results = await app.build('/index.html');
  const { csp } = results[0];
  
  console.log(csp.mode);         // 'ssg-hash' | 'ssr-nonce' | 'external-scripts'
  console.log(csp.header);       // "default-src 'self'; script-src 'self' 'sha256-...';"
  console.log(csp.scriptHashes); // ["sha256-..."]
  console.log(csp.directives);   // { 'default-src': ["'self'"], ... }

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()