Plugins Reference

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:

  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:

  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:

  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:

  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:

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

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.