definePlugin API

Configuration Options #

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

  import { definePlugin } from 'coralite'
  
  const myPlugin = definePlugin({
    name: 'my-plugin', // Required: Unique name for the plugin
  
    // Optional: Main server-side logic
    method: (options, context) => {
      // ... implementation
    },
  
    // Optional: Register custom components
    components: ['./path/to/component.html'],
  
    // Optional: Client-side script configuration
    client: {
      config: { /* ... */ }
      context: { /* ... */ },
    },
  
    // Optional: Server-side lifecycle hooks
    onPageSet: async (data) => { /* ... */ },
    // ... other hooks
  })

Server-Side Hooks #

Plugins can hook into Coralite's build lifecycle to perform actions when pages or components are processed. All hooks support asynchronous operations.

• onBeforeBuild({ path, options }): Called before the build process starts. Useful for copying static assets or initializing global data.
• onPageSet({ elements, properties, page, data }): Called when a page is initially created from a file.
• onPageUpdate({ elements, page, newValue, oldValue }): Called when a page is updated (e.g., during development watch mode).
• onPageDelete(path): Called when a page file is deleted.
• onComponentSet(component): Called when a component is registered.
• onComponentUpdate(component): Called when a component is updated.
• onComponentDelete(component): Called when a component is deleted.
• onBeforePageRender({ component, properties, page, renderContext }): Called immediately before a specific page begins rendering. Allows for late-stage property or AST mutation.
• onAfterPageRender(result): Called after a page has been rendered to HTML. This hook uses an aggregator; plugins can return an array of additional CoraliteResult objects (e.g., for generating RSS feeds or paginated sub-pages).
• onAfterBuild({ results, error, duration }): Called when the entire build process finishes.

Client-Side Scripting #

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

client.context #

Define utilities that will be flattened directly onto the context object in defineComponent scripts in the browser.

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

Note: Context utilities must use the Two-Phase Currying System.

Client Configuration #

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
      },
      // ...
    }
  })

Context Injection #

The client.config is automatically passed as the config property on the globalContext passed to your context factories.

  // Inside client.context
  context: {
    trackEvent: (globalContext) => (localContext) => async (eventName) => {
      const { trackingId } = globalContext.config
      const { default: analyticsLib } = await import('analytics-lib')
  
      analyticsLib.send(trackingId, eventName)
    }
  }

Complete Example: Confetti Plugin #

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: {
      // 1. Define default configuration
      config: {
        particleCount: 100,
        spread: 70
      },
  
      // 2. Create the context utility
      context: {
        explode: (globalContext) => (localContext) => async () => {
          // Access config from global context
          const config = globalContext.config
  
          // 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: config.particleCount,
            spread: 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({
    script: ({ refs, explode }) => {
      const btn = refs('btn')
  
      btn.addEventListener('click', () => {
        explode()
      })
    }
  })
</script>