Coralite CLI

This technical documentation provides an in-depth overview of the Coralite CLI, its command-line options, and usage examples.

Command Structure #

The basic command structure for the Coralite CLI is as follows:

coralite [options]

Options #

The Coralite CLI accepts several options to configure its behavior. Here's a detailed list of available options:

-c, --components <path> (required)
- Description: The file system path to the directory containing Coralite components.
- Example: --components path/to/components
-p, --pages <path> (required)
- Description: The file system path to the directory containing pages that will be rendered using the provided components.
- Example: --pages path/to/pages
-o, --output <path> (required)
- Description: The output directory for the generated site. If the specified directory does not exist, it will be created.
- Example: --output path/to/dist
-s, --standalone <path> (optional)
- Description: The output directory for standalone client-side web components.
- Example: --standalone components
-i, --ignore-attribute <key=value...> (optional)
- Description: Ignore elements by attribute name-value pair during parsing. Multiple pairs can be provided separated by spaces.
- Examples:
  - Ignore <div data-ignore> elements: --ignore-attribute data-ignore=true
  - Ignore multiple elements: --ignore-attribute data-ignore=true class=test-only
--skip-render-attribute <key=value...> (optional)
- Description: Skip rendering elements by attribute name-value pair. Multiple pairs can be provided separated by spaces.
- Example: --skip-render-attribute data-client-only=true
-d, --dry-run (optional)
- Description: Run the CLI in dry-run mode. This displays information about generated documents and their content without actually writing files to the output directory.
- Example: coralite -c src/components -p src/pages -o dist --dry-run
-a, --assets <mapping...> (optional)
- Description: Static assets to copy during build from NPM packages to the output directory. Format is pkg:path:dest (or pkg:path where destination defaults to path). Multiple mappings can be provided separated by spaces.
- Examples:
  - Copy specific file: --assets my-package:dist/style.css:assets/style.css
  - Copy and keep same path: --assets my-package:dist/logo.png

Configuration File Support #

The Coralite CLI automatically looks for a coralite.config.js file in the current working directory. If found, it will merge any plugins defined in the configuration file with the CLI options.

When configuring static assets in the coralite.config.js via defineConfig, you can bypass the package resolution and provide an absolute path to the file using the src property. This handles cases where NPM packages may not explicitly export their package.json or where a custom file path is necessary.

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const wasmPath = require.resolve('@matrix-org/matrix-sdk-crypto-wasm/pkg/matrix_sdk_crypto_wasm_bg.wasm');

export default defineConfig({
  assets: [{ src: wasmPath, dest: 'matrix_sdk_crypto_wasm_bg.wasm' }]
});

Examples #

1. Generate a site with default options:

coralite -c src/components -p src/pages -o dist

2. Ignore specific elements during parsing and run in dry-run mode:

coralite -c src/components -p src/pages -o dist --ignore-attribute data-ignore=true class=test-only --dry-run

3. Using with a configuration file:

When a coralite.config.js file exists in your project root, the CLI will automatically load plugins from it:

coralite -c src/components -p src/pages -o dist

Technical Details #

Under the hood, the Coralite CLI does the following: