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
`properties`	`(context: CoraliteScriptContent) => Promise<Record<string, any>> \| Record<string, any>`	A server-side function or object used for data fetching and state computation. Its returned object is merged into the component's `properties` context. If a value is a function, it is evaluated as a computed property.
`slots`	`Record<string, CoraliteModuleSlotFunction>`	An object defining server-side or client-side processing functions for component slots.
`script`	`(context: CoraliteScriptContent) => void`	The client-side function executed in the browser post-load.

Type Definitions #

CoraliteModuleSlotFunction #

  type CoraliteModuleSlotFunction = (slotNodes: NodeArray, context: CoraliteScriptContent) => NodeArray | string | void

A function that processes slot content. It receives an array of nodes (AST nodes on the server, DOM elements on the client) and the runtime context, and can return an array of nodes, an HTML string, or void to fallback to the original slot content.

CoraliteScriptContent Context Object #

The flattened context object passed to the script execution block:

Property	Type	Description
`instanceId`	`string`	A unique, autogenerated identifier for the specific mounted instance of the component (e.g., `my-widget-1a2b3c`).
`componentId`	`string`	The generic component identifier or tag name (e.g., `my-widget`) defined in the template `id`.
`root`	`HTMLElement`	The Light DOM element. This is the custom element instance itself (the wrapper node).
`module`	`CoraliteModule`	Static metadata for the component, including the template AST and raw script.
`properties`	`Record<string, any>`	The processed token properties, props, and setup data.
`signal`	`AbortSignal \| null`	An `AbortSignal` tied to the component's unmount lifecycle. Use this to prevent memory leaks in event listeners or fetch requests.
`page`	`CoralitePage`	The static environment object containing `url`, `file`, and `meta` information.

Note: Plugin utilities (like refs) and imports are spread directly onto this context object and can be accessed as context.refs, context.imports, etc.

Template IDs and Instance IDs #

It is important to distinguish between the template id and the runtime instanceId:

id / componentId: Refers to the definition identifier (e.g., <template id="my-widget">). This tells the framework what component to render.
instanceId: Refers to the unique, mounted instance of that component. The framework assigns this unique identifier to the context during rendering so plugins and scripts can track specific DOM nodes.

Detailed Comparison: Property Definition Patterns #

The properties option supports two patterns. Understanding the difference is critical for optimizing performance and ensuring reactivity.

Feature	Top-level Function Pattern	Computed Object Pattern
Syntax	`properties: async (context) => ({ ... })`	`properties: { key: (props) => value }`
Context Access	Full access to `page`, `module`, and `renderContext`.	Restricted access; only receives current `properties`.
Reactivity	Server-only. Returns static values to the client.	Isomorphic. Re-runs in the browser on attribute changes.
API Interaction	Best for heavy data fetching (e.g., Database/REST).	Best for internal data transformations.
Efficiency	Processes many keys from one operation.	Each key is isolated and independent.