Coralite Library
Comprehensive documentation for the Coralite library, including constructor, methods, and configuration options for building static sites with HTML modules.
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('my-asset.json', 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()