definePlugin API

The definePlugin function accepts a configuration object with the following options:

  import { definePlugin } from 'coralite'
  
  const myPlugin = definePlugin({
    name: 'my-plugin', // Required: Unique name for the plugin
  
    // Optional: Server-side logic
    server: {
      // Context resolver for component server() blocks
      context: (pluginContext) => {
        return {
          log: (message, context) => {
            console.log(`[${context.id}] ${message}`, context.state)
          }
        }
      },
      // Register custom components
      components: ['./path/to/component-name.html'],
      // Server-side lifecycle hooks
      onPageSet: async (data) => { /* ... */ },
      onBeforeComponentRender: ({ state, session }) => { /* ... */ }
    },
  
    // Optional: Client-side logic
    client: {
      config: { /* static configuration */ },
      context: (pluginContext) => (instanceContext) => {
        return {
          myHelper: () => 'hello'
        }
      }
    }
  })

The server.context property is used to define methods and data available to component server() blocks via the plugin's namespace (e.g. context['logger-plugin']). It follows the Two-Phase Resolver pattern.

• Phase 1 (Global): Receives pluginContext. Used for global initialization and sharing data with other plugins via mutation.
• Phase 2 (Instance): Receives instanceContext. Returns the object exposed to the component. Use instanceContext to access other plugins.

  export default definePlugin({
    name: 'logger-plugin',
    server: {
      config: { prefix: 'LOG' },
      context: (pluginContext) => {
        // Phase 1: Global setup
        pluginContext.sharedLogBuffer = [];
  
        return (instanceContext) => {
          // Phase 2: Per-instance setup
          return {
            log: (message) => {
              console.log(`[${pluginContext.config.prefix}] ${message}`);
            }
          }
        }
      }
    }
  })

Plugins can hook into Coralite's build lifecycle within the server block. All hooks support asynchronous operations. All hooks receive the shared globalContext (as properties) and the plugin's config in their context object.

• onBeforeBuild({ path, options, app, config, ...globalContext }): Called before the build process starts.
• onPageSet({ elements, state, page, data, app, config, ...globalContext }): Called when a page is initially created.
• onPageUpdate({ elements, page, newValue, oldValue, app, config, ...globalContext }): Called when a page is updated.
• onPageDelete({ data, app, config, ...globalContext }): Called when a page file is deleted.
• onComponentSet({ component, app, config, ...globalContext }): Called when a component is registered.
• onComponentUpdate({ component, app, config, ...globalContext }): Called when a component is updated.
• onComponentDelete({ component, app, config, ...globalContext }): Called when a component is deleted.
• onBeforePageRender({ component, state, page, session, app, config, ...globalContext }): Called before a specific page begins rendering.
• onAfterPageRender({ result, session, app, config, ...globalContext }): Called after a page has been rendered. Plugins can return additional CoraliteResult objects.
• onBeforeComponentRender({ state, componentId, instanceId, refs, session, app, config, ...globalContext }): Called before a specific component instance is rendered.
• onAfterComponentRender({ result, state, componentId, instanceId, session, app, config, ...globalContext }): Called after a component instance is rendered.
• onAfterBuild({ results, error, duration, app, config, ...globalContext }): Called when the entire build process finishes.

The client property is powerful: it allows you to inject code that runs in the browser. This code is bundled with your application.

Define utilities that will be available via the plugin's namespace on the context object in defineComponent client-side scripts.

  definePlugin({
    name: 'utils',
    client: {
      context: (pluginContext) => (instanceContext) => {
        return {
          formatDate: (date) => {
            return new Date(date).toLocaleDateString()
          }
        }
      }
    }
  })

Note: Context utilities use the Two-Phase Resolver pattern.

The client.config object allows you to pass static configuration data from the server (where the plugin is defined) to the client. This is useful for API keys, theme settings, or feature flags.

  definePlugin({
    name: 'analytics',
    client: {
      config: {
        trackingId: 'UA-123456-7',
        debug: true
      },
      // ...
    }
  })

The client.config is automatically passed as a property of the single argument to your context factories. Additionally, you can mutate the context in Phase 1 to expose services to downstream plugins.

  // Inside client.context
  context: (pluginContext) => {
    const { trackingId } = pluginContext.config;
    
    // ✨ EXPOSE TO DOWNSTREAM PLUGINS
    pluginContext.analyticsReady = true;
  
    return (instanceContext) => {
      return {
        trackEvent: async (eventName) => {
          const { default: analyticsLib } = await import('analytics-lib')
          analyticsLib.send(trackingId, eventName)
        }
      }
    }
  }

Let's build a plugin that triggers a confetti explosion using a remote library and allows configuration of particle count.

  import { definePlugin } from 'coralite'
  
  export default definePlugin({
    name: 'confetti-plugin',
    client: {
      // Define configuration
      config: {
        particleCount: 100,
        spread: 70
      },
  
      // Create the context utility
      context: (pluginContext) => (instanceContext) => {
        return {
          explode: async () => {
            // Dynamically import the library (auto-bundled by AST)
            const { default: confetti } = await import('https://esm.sh/canvas-confetti@1.6.0')
  
            // Use the library with the config
            confetti({
              particleCount: pluginContext.config.particleCount,
              spread: pluginContext.config.spread,
              origin: { y: 0.6 }
            })
          }
        }
      }
    }
  })

Usage in a component:

<template id="celebration-button">
  <button ref="btn">Celebrate!</button>
</template>

<script type="module">  
  import { defineComponent } from 'coralite'
  
  export default defineComponent({
    client: (context) => {
      const btn = context.refs('btn')
      const { explode } = context['confetti-plugin']
  
      btn.addEventListener('click', () => {
        explode()
      })
    }
  })
</script>