Advanced Guide: Authoring Plugins

Plugins are the primary way to extend Coralite's functionality. The framework's architecture is designed to be highly extensible via the definePlugin function.

With plugins, you can hook deep into the build lifecycle, register custom components globally, bundle external scripts, and inject custom helper functions directly into the frontend.

The Conceptual Flow #

Authoring a plugin involves understanding how Coralite synthesizes server-side rendering and client-side hydration. When you register a plugin, Coralite integrates it through the following flow:

1. Registration & Bootstrapping: Coralite loads your plugin via definePlugin, reading its client.config and executing its client.context setup to prepare client-side utilities.
2. Server Execution: As the generator processes pages and encounters dynamic components, it fires your plugin's lifecycle hooks (e.g., onPageSet, onBeforePageRender).
3. Data Binding & Injection: Coralite processes the component's tokens, properties, and slots. Any server-fetched data is bridged into the component's properties object.
4. Client Hydration: Finally, Coralite serializes your component's script and your plugin's custom `client.context` utilities. When the browser loads the page, the utilities are securely flattened and spread directly onto the runtime context, enabling dynamic interactions.

Server-Side Lifecycle Hooks #

Plugins can hook into almost every phase of Coralite's build lifecycle to perform actions when files are processed or rendering occurs.

• Page Lifecycle:
  • onPageSet(data): Called when a page is created. Ideal for extracting metadata (like the built-in metadata plugin).
  • onPageUpdate(data): Called when a page is updated.
  • onPageDelete(path): Called when a page is deleted.
• Component Lifecycle:
  • onComponentSet(data): Called when a component is registered.
  • onComponentUpdate(data): Called when a component's source file is updated.
  • onComponentDelete(path): Called when a component is deleted.
• Render Lifecycle:
  • onBeforePageRender(data): Called right before a specific page's HTML is compiled. Useful for modifying the raw document data before rendering. Note: Inside plugin hooks, the Coralite instance is bound to this.
  • onAfterPageRender(data): Called immediately after a specific page's HTML is compiled.
• Build Lifecycle:
  • onBeforeBuild(): Called before the entire static generation process starts.
  • onAfterBuild(): Called when the entire build process finishes.

Global Component Registration #

Plugins can distribute their own HTML components. By providing an array of file paths to the components property in your plugin configuration, Coralite automatically reads, parses, and registers these files as global components during initialization.

This means users of your plugin can instantly use your custom tags (e.g., <my-awesome-slider>) without having to copy the HTML files into their own project's src/components/ directory.

Injecting Client Helpers #

The most powerful feature of Coralite plugins is the ability to provide reusable functionality directly to component scripts using client.context.

Context utilities are flattened directly onto the root context object available in every script execution block. However, because Coralite is a static site generator, there is a strict boundary between server code and client code.

The Factory Pattern #

Helpers must be structured using a two-phase currying system that executes server-side. The outermost function receives the global context, and it must return a second function that receives the local Web Component instance context. This second function then returns the actual callable utility function used by the user's script.

To use client-only APIs (like window, document, or the injected AbortSignal), the injected helper function must encapsulate that logic within the final returned function.

  // Server-side definition in definePlugin
  client: {
    context: {
      // Phase 1: Runs on the SERVER and receives global context
      trackEvent: (globalContext) => {
        const apiKey = globalContext.config.apiKey;
  
        // Phase 2: Receives the local Web Component instance context
        return ({ signal }) => {
  
          // Phase 3: The actual function accessible on the CLIENT
          return (buttonElement, eventName) => {
  
            // Now we can safely use browser APIs and component lifecycle signals
            buttonElement.addEventListener('click', () => {
              window.navigator.sendBeacon('https://api.analytics.com', JSON.stringify({
                key: apiKey,
                event: eventName
              }));
            }, { signal });
  
          };
        }
      }
    }
  }

Zero-Config Dependencies #

Unlike earlier versions of Coralite, V1 removes the need for manual dependency arrays like client.imports or client.components. The underlying AST parser automatically detects dynamic imports (e.g., await import('my-analytics-sdk')) inside the actual runtime logic of your context utilities and bundles them automatically.

Ready to build your plugin? Consult the strict API signatures and configuration options in the definePlugin API Reference.