defineComponent API Reference

This document details the exact API signatures, options, and types for Coralite's core defineComponent plugin.

For a conceptual guide on how to use dynamic components, see the Dynamic Components Guide.

Signature #

  function defineComponent(options: DefineComponentOptions): PluginDefinition

Options Object (DefineComponentOptions) #

The defineComponent function accepts a single configuration object with the following optional properties:

Property	Type	Description
`tokens`	`Record<string, string \| CoraliteModuleTokenFunction>`	An object defining computed or static values available for template interpolation.
`slots`	`Record<string, CoraliteModuleSlotFunction>`	An object defining server-side processing functions for component slots.
`client`	`ClientOptions`	An object defining server-side setup and client-side scripts.

Type Definitions #

CoraliteModuleTokenFunction #

  type CoraliteModuleTokenFunction = (values: Record&lt;string, any&gt;) => any | Promise&lt;any&gt;

A function that evaluates data at build time. It receives a values object containing element attributes and page metadata (prefixed with meta_ and $).

CoraliteModuleSlotFunction #

  type CoraliteModuleSlotFunction = (slotNodes: ParsedHTMLNode[], values: Record&lt;string, any&gt;) => ParsedHTMLNode[] | string | void

A function that processes slot content. It receives an array of parsed HTML nodes and the current token values, and can return an array of parsed HTML nodes, an HTML string to be parsed, or void/undefined to fallback to the original slot content.

ClientOptions #

Property	Type	Description
`setup`	`(values: Record<string, any>) => Promise<Record<string, any>>`	An asynchronous server-side function. Its returned object is merged into the component's `values`.
`script`	`(context: CoraliteScriptContent) => void`	The client-side function executed in the browser post-load.
`imports`	`Array<ImportDefinition>`	An array defining component-level external dependencies to be bundled.
`components`	`Array<string>`	An array of string dependencies. Declares other imperative Web Components created in the script.

CoraliteScriptContent Context Object #

The context object passed to the client.script function:

Property	Type	Description
`id`	`string`	A unique identifier for the specific component instance.
`componentId`	`string` (optional)	The generic component identifier.
`root`	`ShadowRoot \| Document`	The DOM root. This will be the `ShadowRoot` for imperative web components or the standard Document (`window.document`) for declarative components.
`values`	`Record<string, any>`	The processed token values, props, and setup data.
`refs`	`Record<string, string>`	A map of instance reference IDs.
`helpers`	`object`	Client-side utilities provided by plugins (e.g., `helpers.refs` and `helpers.imports`).
`components`	`string[]`	An array of string dependencies if imperative web components are used.

ImportDefinition #

Objects in the client.imports array:

Property	Type	Description
`specifier`	`string` (Required)	The path or URL of the module.
`defaultExport`	`string`	The name to assign to the default export.
`namedExports`	`string[]`	List of named exports to import. Supports `"original as alias"` syntax.
`namespaceExport`	`string`	Import the entire module as a namespace (`import * as Name`).
`attributes`	`object`	Import attributes (e.g., `{ type: 'json' }`).

ℹ️ The Static Import Ban

Static import statements cannot be used directly inside a client.script block. Doing so will result in a build failure. Instead, you must declare all external dependencies via the client.imports array, and they will become available at runtime via the helpers.imports object.