definePlugin API

The definePlugin function is the entry point for extending Coralite's functionality. It allows you to inject server-side logic, register custom templates, and most importantly, bundle and configure client-side scripts that can be used by your components.

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: {
      setup: async () => { /* ... */ },
      helpers: { /* ... */ },
      imports: [ /* ... */],
      config: { /* ... */ }
    },
  
    // 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.

onPageSet(data): Called when a page is created or updated.
onPageUpdate(data): Called when a page is updated.
onPageDelete(path): Called when a page is deleted.
onComponentSet(data): Called when a component is registered.
onBeforeBuild(): Called before the build process starts.
onAfterBuild(): 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.setup #

A client-side function that runs when the plugin is registered in the browser. Use it to prepare data or environment for the plugin in the frontend.

client.helpers #

Define helper functions that will be available to defineComponent scripts in the browser.

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

Note: Helper functions must be "factory functions" that accept a context object and return the actual function to be used.

Client Imports #

Use client.imports to make external libraries (npm packages, local files, or remote URLs) available to your client-side helpers. Coralite handles the bundling and injection for you.

Import Types #

Remote Import (ESM) #

Import a library directly from a CDN.

  imports: [
    {
      specifier: 'https://esm.sh/canvas-confetti@1.6.0',
      defaultExport: 'confetti'
    }
  ]

Local Import #

Import a local JavaScript module.

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

JSON Import #

Import a JSON file as a module.

  imports: [
    {
      specifier: './data/config.json',
      defaultExport: 'config',
      attributes: { type: 'json' }
    }
  ]

Import Options #

specifier (string): The path or URL of the module.
defaultExport (string): The name to assign to the default export.
namedExports (string[]): List of named exports to import. Supports "original as alias" syntax.
namespaceExport (string): Import the entire module as a namespace (import * as Name).

Client Configuration #

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

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

Context Injection #

Both client.imports and client.config are automatically injected into the context object passed to your helper factories.

Access them via:

context.imports: Contains all imported modules/exports.
context.config: Contains the configuration object.

  // Inside client.helpers
  helpers: {
    trackEvent: (context) => (eventName) => {
      const { trackingId } = context.config
      const { analyticsLib } = context.imports
  
      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. Import the library
      imports: [
        {
          specifier: 'https://esm.sh/canvas-confetti@1.6.0',
          defaultExport: 'confetti'
        }
      ],
  
      // 2. Define default configuration
      config: {
        particleCount: 100,
        spread: 70
      },
  
      // 3. Create the helper
      helpers: {
        explode: (context) => () => {
          // Access injected imports and config
          const confetti = context.imports.confetti
          const config = context.config
  
          if (!confetti) {
            console.warn('Confetti library not loaded')
            return
          }
  
          // 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: (context, helpers) => {
      const btn = helpers.refs('btn')
  
      // The 'explode' helper is now available on 'helpers'
      const explode = helpers.explode
  
      btn.addEventListener('click', () => {
        explode()
      })
    }
  })
</script>