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 \| TokenFunction>`	An object defining computed or static values available for template interpolation.
`slots`	`Record<string, SlotFunction>`	An object defining server-side processing functions for component slots.
`client`	`ClientOptions`	An object defining server-side setup and client-side scripts.

Type Definitions #

TokenFunction #

  type TokenFunction = (values: Record&lt;string, any&gt;) => string

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

SlotFunction #

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

A function that processes slot content. It receives an array of parsed HTML nodes and the current token values, and must return an array of parsed HTML nodes.

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.

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.
`document`	`object`	The Coralite document interface (or a mocked interface with `getElementById`).
`values`	`Record<string, any>`	The processed token values, props, and setup data.
`refs`	`Record<string, string>`	A map of instance reference IDs.
`root`	`ShadowRoot` (optional)	The Shadow Root boundary (if compiled as a standalone Web Component).
`helpers`	`object`	Client-side utilities provided by plugins (e.g., `helpers.refs` and `helpers.imports`).

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' }`).