AlpineJS Skill: Creating Local Plugins with Alpine.plugin()

Alpine.plugin(pluginFunction): This is the core method for registering a new plugin. You pass it a function (the pluginFunction). This function receives the global Alpine object as its first argument. Inside this function, you can call other Alpine methods like Alpine.directive(), Alpine.store(), and Alpine.magic() to extend Alpine's functionality.

const myCustomPlugin = (alpineInstance) => {
    // Use alpineInstance to register directives, stores, magic, etc.
    // Example: alpineInstance.directive('my-new-directive', () => { /* ... */ });
    alpineInstance.magic('myHelper', () => 'Hello from plugin!');
};

// This registration happens inside an 'alpine:init' listener
Alpine.plugin(myCustomPlugin);
                        

Alpine.directive() (within plugin): Used to create new custom attributes (directives) that you can use in your HTML (e.g., x-my-directive). The callback function for a directive typically receives arguments like el (the DOM element the directive is on), an object containing expression (the value of the attribute), and an object with utility functions like evaluate, evaluateLater, and effect.

// Inside your pluginFunction:
alpineInstance.directive('highlight', (el, { expression }, { evaluate }) => {
    const color = evaluate(expression) || 'yellow'; // Evaluate the expression string
    el.style.backgroundColor = color;
    el.style.padding = '0.25rem';
});
// Usage: <div x-highlight="'lightblue'">Highlighted Content!</div>
// Or    <div x-highlight>Default Highlight!</div>
                        

Alpine.store() (within plugin): Allows your plugin to register global reactive data stores. These stores can be accessed by any Alpine component using Alpine.store('storeName') in JavaScript or $store.storeName in HTML templates.

// Inside your pluginFunction:
alpineInstance.store('appSettings', {
    theme: 'light',
    toggleTheme() { this.theme = (this.theme === 'light' ? 'dark' : 'light'); }
});
// Usage: <div x-text="$store.appSettings.theme"></div>
//        <button @click="$store.appSettings.toggleTheme()">Toggle Theme</button>
                        

Alpine.magic() (within plugin): Lets you register "magic" properties or methods that become available directly on the component's scope (e.g., $myMagic) or on the global Alpine object (e.g., Alpine.$myMagic). They provide convenient shortcuts or utilities.

// Inside your pluginFunction:
alpineInstance.magic('uppercase', (el) => { // el is the current component's root element
    return (text) => String(text).toUpperCase();
});
// Usage: <span x-text="$uppercase('hello world')"></span>
// Output: HELLO WORLD
                        

alpine:init: This DOM event is crucial. It fires once Alpine.js has initialized itself but before it initializes any components on the page (i.e., processes elements with x-data). You must register your plugins within an event listener for alpine:init to ensure they are available when components are processed.

document.addEventListener('alpine:init', () => {
    // Register plugins first
    Alpine.plugin(myUIKitPlugin);
    Alpine.plugin(anotherPlugin);

    // Then define stores (if any)
    Alpine.store('globalState', { /* ... */ });

    // Then define components
    Alpine.data('myComponent', () => ({ /* ... */ }));
});