GitHub v1.3.1

Plugins Reference

Plugin

Complete API reference for creating and configuring Coralite plugins with definePlugin, including core plugins, two-phase context resolvers, configuration schemas, and lifecycle hooks.

Coralite provides an extensible plugin system built around definePlugin. Plugins can extend server compilation, inject browser runtime utilities, register components, and manage build lifecycle hooks.

1. The definePlugin Function

Define custom framework plugins using the definePlugin helper exported from coralite:

javascript
Code copied!
  import { definePlugin } from 'coralite'
  
  export default definePlugin({
    name: 'my-plugin',
    config: {
      // Plugin configuration schema
    },
    // Top-level ubiquitous context (available across server, getters, client, slots, style)
    context: ({ app, config }) => (instanceContext) => ({
      // Ambient utilities (mutually exclusive with server.context / client.context)
    }),
    server: {
      // Server-side hooks, context, and components
    },
    client: {
      // Client-side browser runtime hooks and context
    }
  })

2. Auto-Registered Core Plugins

Coralite automatically registers three core plugins in every application. You do not need to manually import or register them in coralite.config.js:

  • lists — Provides fine-grained DOM list rendering, keyed collection stores, virtualization, and layout support.
  • router — Provides client-side SPA routing, outlet wrapping, route transition events, and navigation guards.
  • store — Implements application-wide signal-backed global state management.

3. Plugin Configuration & Schemas

Plugins define their configuration schema using primitive type constructors (String, Number, Boolean) within the config block, identical to component attribute schemas:

javascript
Code copied!
  import { definePlugin } from 'coralite'
  
  export const myPlugin = definePlugin({
    name: 'my-plugin',
    config: {
      apiKey: { type: String, required: true },
      timeout: { type: Number, default: 5000 },
      debug: { type: Boolean, default: false }
    },
    server: {
      context: (pluginContext) => {
        // Access validated user config
        const { apiKey, timeout } = pluginContext.config
        return { apiKey, timeout }
      }
    }
  })

Consumers register and configure plugins in coralite.config.js by invoking the plugin function with options:

javascript
Code copied!
  import { defineConfig } from 'coralite'
  import { myPlugin } from './plugins/my-plugin.js'
  
  export default defineConfig({
    output: 'dist',
    components: 'src/components',
    pages: 'src/pages',
    plugins: [
      myPlugin({
        apiKey: 'xyz-12345',
        debug: true
      })
    ]
  })

4. The Two-Phase Context Resolver

Client runtime utilities exposed to component client() blocks use a Two-Phase Resolver pattern to safely isolate global setup from per-component instance execution:

javascript
Code copied!
  import { definePlugin } from 'coralite'
  
  export default definePlugin({
    name: 'analytics',
    config: {
      trackingId: { type: String, required: true }
    },
    client: {
      context: (pluginContext) => {
        // Phase 1: Runs once during boot.
        // Useful for global singletons or dynamic module imports.
        const trackingId = pluginContext.config.trackingId
  
        return (instanceContext) => {
          // Phase 2: Runs once per component instance.
          // Receives instance state, signal, refs, and root element.
          const { signal } = instanceContext
  
          return {
            track: (eventName, payload) => {
              console.log(`[${trackingId}] Event: ${eventName}`, payload)
            }
          }
        }
      }
    }
  })

In component client() blocks, destructured plugin methods are accessed directly from the context object:

javascript
Code copied!
  import { defineComponent } from 'coralite'
  
  export default defineComponent({
    client({ analytics, refs }) {
      refs.button.addEventListener('click', () => {
        analytics.track('button_click', { id: 'submit' })
      })
    }
  })

Imperative Custom Elements

Client-side plugin functions may create custom elements imperatively with document.createElement() or HTML assignment. Coralite scans and rewrites these calls to its on-demand component loader, so a literal custom-element tag is loaded and upgraded without a manual loadComponent() call:

javascript
Code copied!
  import { definePlugin } from 'coralite'
  
  export default definePlugin({
    name: 'widgets',
    client: {
      context: () => (instanceContext) => ({
        create (container) {
          const child = document.createElement('my-widget')
          container.appendChild(child)
  
          container.insertAdjacentHTML('beforeend', '<my-widget></my-widget>')
        }
      })
    }
  })

Use phase 2 of client.context or client.init for element creation. Phase 1 runs before the component loader is ready, so synchronous DOM creation there is not upgraded. Dynamically imported helper modules are bundled but not AST-scanned; keep them pure or use window.__coralite__.dom.createElement(tag) / await window.__coralite__.dom.loadComponent(tag). Plugin dependencies controls registration order, not custom-element tracking.

See the Imperative Components Reference for scan boundaries, literal vs. dynamic tags, runtime APIs, upgrade timing, ownership, styling, testing, and troubleshooting.

5. Lifecycle Hooks

Plugins intercept framework events across build and runtime phases via lifecycle hooks:

Server Hooks

Hook Description
onBeforeBuild Fires before compilation starts. Useful for environment checks or asset preparation.
onPageSet Fires when a page record is initially registered during collection.
onPageUpdate Fires in watch mode when a page file is modified.
onPageDelete Fires in watch mode when a page file is removed.
onBeforePageRender Fires before rendering a page to static HTML. Can inspect or modify page AST nodes.
onAfterPageRender Fires after page render completes. Can transform generated HTML output.
onAfterBuild Fires after all pages and components have completed building.

Client Hooks

Hook Description
client.init Runs once in the browser runtime when Coralite initializes.
onBeforeComponentRender Runs before a client component mounts into the DOM.
onAfterComponentRender Runs after a component has mounted and completed initial hydration.
onDisconnected Runs when a component instance is removed from the DOM.