GitHub v1.3.1

definePlugin

Stable

Extend Coralite with custom build-time behavior and inject context into components and pages.

Plugin Schema

A plugin is a standard ES module that exports a configuration object via definePlugin. Plugins are registered in coralite.config.js and injected into the execution context of every component and page.

javascript
Code copied!
  import { definePlugin } from 'coralite'
  
  export default definePlugin({
    name: 'my-plugin',
    context: (pluginContext) => (instanceContext) => ({
      // Phase 1: Runs once at initialization
      // Phase 2: Runs per component/page instance
      $greet: (name) => `Hello, ${name}!`
    })
  })

The Two-Phase Curried Context

The context function uses a curried signature. This ensures that expensive setup (Phase 1) runs only once, while the instance-specific context (Phase 2) is lazily resolved for each component or page.

javascript
Code copied!
  export default definePlugin({
    name: 'analytics',
    context: (pluginCtx) => (instanceCtx) => ({
      track: (event) => {
        // instanceCtx gives access to the component's state and route
        console.log(`[${instanceCtx.route.path}] ${event}`)
      }
    })
  })

Environment-Specific Context

For context that should only exist on the server or only in the browser, use the server.context and client.context sub-objects. They must use the same curried signature.

javascript
Code copied!
  export default definePlugin({
    name: 'server-only',
    server: {
      context: () => () => ({
        queryDb: async (sql) => { /* ... */ }
      })
    },
    client: {
      context: () => () => ({
        trackClick: (el) => { /* ... */ }
      })
    }
  })
CORALITE-P301: Single-Phase Context

The context function must return a function, not an object. If you return { $greet: ... } directly, Coralite throws CORALITE-P301. Always use the two-phase curried signature: (pluginCtx) => (instanceCtx) => ({ ... }).

Reserved Keys

Coralite reserves several keys on the execution context: state, route, app, session, signal, store, page, refs, emit, observe, updateComplete. If your plugin exports a key with the same name, Coralite will preserve the framework key and emit a warning in development mode.