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 Components Guide.

Signature #

  function defineComponent(options: DefineComponentOptions): PluginDefinition

Options Object (DefineComponentOptions) #

The defineComponent function accepts a single configuration object with the following isolated blocks. Note: All components MUST have a hyphen in their name (e.g., <my-component>).

Property	Type	Description
`attributes`	`Record<string, AttributeSchema>`	Defines and coerces HTML attributes into JS primitives.
`server`	`(context: CoraliteServerContext) => Promise<Record<string, any>>`	A server-side async function for fetching initial state. Stripped from the client bundle. Formerly known as `data`.
`getters`	`Record<string, (state: ReadonlyState) => any>`	Pure functions for derived state. Receives a read-only state proxy.
`client`	`(context: CoraliteScriptContext) => void`	The client-side controller. Receives a read/write state proxy. Formerly known as `script`.
`slots`	`Record<string, CoraliteModuleSlotFunction>`	Functions for processing and transforming slot content.

1. attributes #

The attributes block defines the inputs your component accepts from HTML. Coralite automatically coerces these values into the specified types.

  attributes: { 
      theme: { type: String, default: 'light' },
      maxItems: { type: Number, default: 10 },
      expanded: { type: Boolean, default: false }
  }

Strict Primitive Rule

To prevent complex JSON-in-HTML parsing errors and ensure performance, attributes only support String, Number, and Boolean. Use the server block or slots for complex data structures.

Note: If you use the no-hydration attribute, the host tag is completely removed (spliced) and replaced by its contents. Learn more in the SSR Guide.

2. server (Server-Side) #

The server block is used for heavy-lifting, such as database queries or API calls. This code runs only on the server during the build process and is completely removed from the JavaScript sent to the browser. Formerly known as data.

  async server(context) {
      const users = await db.users.findMany();
      return { users };
  }

3. getters (Derived State) #

Getters are pure functions used to calculate derived data. They are reactive; if an attribute or a data value changes, the getter automatically re-calculates.

  getters: {
      // state is a Read-Only Proxy here
      visibleUsers: (state) => state.users.slice(0, state.maxItems)
  }

4. client (Client-Side) #

The client block is the controller for your component in the browser. This is where you add event listeners and mutate state. Formerly known as script.

  client: ({ state, signal, refs }) => {
      // Access unique DOM elements via the 'refs' utility
      const btn = refs('loadMoreBtn');
      
      btn.addEventListener('click', () => {
          // Imperative mutation triggers DOM updates
          state.maxItems += 10; 
      }, { signal }); // Use the provided 'signal' for auto-cleanup
  }

CoraliteScriptContext #

Property	Type	Description
`state`	`Proxy`	The Read/Write reactive state (Attributes + Data + Getters).
`signal`	`AbortSignal`	Used for cleaning up event listeners and aborting fetches on unmount.
`root`	`HTMLElement`	The DOM element instance of the component.
`instanceId`	`string`	A unique identifier for this specific instance.
`refs`	`(id: string) => HTMLElement \| null`	A utility to query unique elements by their `ref` name.

5. slots #

Allows you to intercept and transform content passed into your component's slots.

  type CoraliteModuleSlotFunction = (slotNodes: Node[], state: any) => Node[] | string | undefined | null

The Void = Bypass Paradigm #

To ensure high performance and prevent unnecessary re-rendering during client-side hydration, Coralite uses a "Void = Bypass" approach for slot transformations:

undefined (Bypass): Signals the framework to skip processing and preserve the current content. On the server, it preserves the original AST nodes; on the client, it preserves the existing DOM nodes. Use this in the browser to prevent flushing SSR-rendered content.
null, "", or [] (Clear): Explicitly instructs the framework to remove all content from the slot.

  slots: {
      default: (nodes, state) => {
          // Bypass hydration in the browser to preserve SSR content
          if (typeof window !== 'undefined') return undefined;
  
          // Otherwise, perform complex transformation on the server
          return nodes.map(n => transform(n));
      }
  }