createPlugin API

Configuration Options #

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

  import { createPlugin } from 'coralite'
  
  const myPlugin = createPlugin({
    name: 'my-plugin', // Required: Unique name for the plugin
    
    // Optional: Main server-side logic
    method: (options, context) => {
      // ... implementation
    },
  
    // Optional: Register custom templates
    templates: ['./path/to/template.html'],
  
    // Optional: Client-side script configuration
    script: {
      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 templates 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.
• onTemplateSet(data): Called when a template is registered.
• onBuildComplete(): Called when the entire build process finishes.

Client-Side Scripting #

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

script.setup #

A server-side function that runs during the build process to prepare data or environment for the plugin. Use it to fetch remote data or validate configuration.

script.helpers #

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

  createPlugin({
    name: 'utils',
    script: {
      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.

Script Imports #

Use script.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.

  createPlugin({
    name: 'analytics',
    script: {
      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).

Script Configuration #

The script.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.

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

Context Injection #

Both script.imports and script.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 script.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 { createPlugin } from 'coralite'
  
  export default createPlugin({
    name: 'confetti-plugin',
    script: {
      // 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 }
          })
        }
      }
    }
  })