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

  createPlugin({
  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.

  createPlugin({
  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.

  createPlugin({
  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 { createPlugin } from 'coralite'
  
  export default createPlugin({
  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 }
  })
  }
  }
  }
  })