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 options:

Property	Type	Default	Description
`components`	`string`	-	Path to the directory containing Coralite component files.
`pages`	`string`	-	Path to the directory containing page files.
`output`	`string`	-	Path to the output directory.
`plugins`	`CoralitePluginInstance[]`	`[]`	Array of plugin instances to register.
`assets`	`CoraliteStaticAsset[]`	`[]`	Static assets to copy during build. See Static Assets Plugin.
`baseURL`	`string`	`'/'`	Base URL for asset paths.
`ignoreByAttribute`	`IgnoreByAttribute[]`	`[]`	Elements to ignore by attribute name-value pair during parsing.
`skipRenderByAttribute`	`string[]`	`[]`	Attribute names that trigger elements to be excluded from the final render.
`onError`	`CoraliteOnError`	Default handler	Callback for handling errors and warnings.
`mode`	`'production' \| 'development' \| 'testing'`	`'production'`	Build mode. Use `'testing'` for zero-config E2E environments.
`testing`	`CoraliteTestingConfig`	`{}`	Optional configuration for testing mode, including server-side mocks.
`incremental`	`boolean`	`true`	Whether to skip rebuilding unchanged pages and components via change detection. Set to `false` to force a full rebuild on every run.
`csp`	`CoraliteCSPConfig`	`undefined`	Content Security Policy (CSP Level 2/3) configuration options.

Content Security Policy (csp) #

Coralite provides build-time and runtime Content Security Policy support for SSG and SSR environments.

  // coralite.config.js
  import { defineConfig } from 'coralite-scripts';
  
  export default defineConfig({
    output: 'dist',
    pages: 'src/pages',
    templates: 'src/templates',
    csp: {
      enabled: true,
      hashAlgorithm: 'sha256',
      injectMeta: true,
      reportOnly: false,
      externalScripts: false,
      externalStyles: false,
      directives: {
        'default-src': ["'self'"],
        'script-src': ["'self'"],
        'style-src': ["'self'"]
      }
    }
  });

The csp sub-options include:

Sub-Property	Type	Default	Description
`enabled`	`boolean`	`true`	Enables or disables CSP calculation and meta tag injection.
`nonce`	`string`	`undefined`	Cryptographic random nonce for per-request SSR propagation (SSR Nonce Mode).
`hashAlgorithm`	`'sha256' \| 'sha384' \| 'sha512'`	`'sha256'`	Hashing algorithm for inline text nodes (SSG Hash Mode).
`injectMeta`	`boolean`	`true`	Automatically injects `<meta http-equiv="Content-Security-Policy" content="...">` into `<head>`.
`reportOnly`	`boolean`	`false`	Uses report-only meta/header naming instead of enforcing policies.
`externalScripts`	`boolean`	`false`	Bundles page runtime scripts into external JS files (`assets/js/pages/[page]-[hash].js`).
`externalStyles`	`boolean`	`false`	Bundles component scoped and inline styles into external CSS files (`assets/css/coralite-inline-[hash].css`).
`directives`	`CoraliteCSPDirectives`	Default directives	Custom directive overrides merged into standard CSP rules.

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.

Environment Considerations #

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