Configuration Reference

Coralite is configured using a coralite.config.js file in the root of your project. This file exports a configuration object that defines input paths, output directories, plugins, and build options.

If you prefer TypeScript or type hinting, you can use the defineConfig helper from coralite-scripts.

  // coralite.config.js
  import { defineConfig } from 'coralite-scripts';
  import myPlugin from './plugins/my-plugin.js';
  
  export default defineConfig({
    components: 'src/components',
    pages: 'src/pages',
    output: 'dist',
    plugins: [myPlugin],
    onError: ({ level, message, error }) => {
      if (level === 'ERR') {
        console.error(`[FATAL] ${message}`);
        if (error) console.error(error.stack);
      } else {
        console.warn(`[${level}] ${message}`);
      }
    }
  });

Configuration Options #

The CoraliteConfig object accepts the following properties:

Property	Type	Default	Description
`components`	`string`	-	Path to the directory containing Coralite components.
`pages`	`string`	-	Path to the directory containing pages.
`output`	`string`	-	Path to the output directory.
`plugins`	`CoralitePluginInstance[]`	`[]`	Array of plugin instances.
`baseURL`	`string`	`'/'`	Base URL for asset paths.
`onError`	`CoraliteOnError`	Default handler	Callback for handling errors and warnings. The Coralite instance securely wraps this callback inside its own internal `handleError` function. By default, it throws for `'ERR'` and logs to console for others.
`mode`	`'production' \| 'development'`	`'production'`	Build mode.

Error & Warning Handling (onError) #

Coralite provides a centralized onError callback in its configuration to handle framework-level issues.

The API Signature

The onError callback receives a single structured error object containing:

level: The severity of the issue ('WARN', 'ERR', or 'LOG').
message: A descriptive string explaining the issue.
error: (Optional) The original Error object, useful for stack traces.

The Default Behavior

If omitted, Coralite defaults to using console.warn and console.log for warnings and logs. However, for level 'ERR', the default handler throws an actual Error with the provided message to intentionally break the build pipeline if an unrecoverable issue occurs.

Internal Handling

The Coralite instance securely wraps the custom (or default) error callback inside an internal handleError method. This allows internal functions (like the HTML or module parsers) to use a safe, bound reference to report issues seamlessly without handling the configuration logic themselves.

Use Cases

Overriding this configuration is particularly useful if you are building a custom CLI logger, integrating an external error-tracking service (like Sentry) during the build process, or needing to gracefully silence specific warnings.

For a complete tutorial on implementing this, check out our guide on Advanced Error Logging.

Assets Plugin (coralite-scripts) #

The assets property (processed by staticAssetPlugin) expects an array of objects. These objects must define a dest property. To determine the source, you must define either pkg (and optionally path) or an explicit src path to bypass standard package resolution.

Environment Considerations #

When running Coralite using the coralite-scripts development mode (e.g., npm run dev or mode === 'dev'), the output directory is automatically overridden to a temporary .coralite/build folder to isolate build artifacts from production outputs. This directory is automatically cleaned up on server startup and graceful exit.