AlpineJS Skill: Global Stores with Alpine.store()

Alpine.store(name, object): This is the primary function used to define a global store. You call it typically within an alpine:init event listener. The name is a string that you'll use to access the store (e.g., 'cart', 'userSettings'). The object is a JavaScript object containing the store's data (properties) and methods to manipulate that data. Properties within this object will be reactive; when they change, any part of your UI bound to them will automatically update.

// Example: Defining a simple theme store
document.addEventListener('alpine:init', () => {
  Alpine.store('theme', {
    darkMode: false,
    toggle() {
      this.darkMode = !this.darkMode;
    }
  });
});

$store.storeName.property: Once a store is defined, you can access its properties from any Alpine component using the $store magic property. For example, if you defined a store named 'cart' with a property items, you would access it as $store.cart.items. This access is reactive. If $store.cart.items changes, any HTML element displaying it will update.

<!-- Example: Displaying a store property -->
<div x-data>
  Number of items in cart: <span x-text="$store.cart.totalItems"></span>
</div>

Methods within store to modify state: Stores can (and should) contain methods to encapsulate the logic for modifying their state. These methods are defined like regular JavaScript object methods. Inside these methods, this refers to the store object itself, allowing you to modify its properties. Calling these methods (e.g., $store.cart.addItem({id:1, name:'Product'})) will trigger reactivity if they change store properties.

// Example: Store with a method
Alpine.store('counter', {
  count: 0,
  increment() {
    this.count++; // 'this' refers to the 'counter' store object
  }
});

<!-- Example: Calling a store method -->
<button @click="$store.counter.increment()">Increment</button>

alpine:init: This is a custom browser event dispatched by Alpine.js when it has finished its initial setup and is ready to register components and stores. It's crucial to define your Alpine.store() calls within an event listener for alpine:init. This ensures that Alpine is fully loaded and can correctly process your store definitions before any components on the page try to access them.

document.addEventListener('alpine:init', () => {
  // It's safe to define stores and components here
  Alpine.store('myStore', { /* ... */ });
  Alpine.data('myComponent', () => ({ /* ... */ }));
});

Stores must be defined before access: Make sure Alpine.store('yourStoreName', ...) is executed *before* any Alpine component (x-data) that tries to use $store.yourStoreName is initialized. The standard way to ensure this is to define all stores inside a document.addEventListener('alpine:init', () => { ... }); block. If a component tries to access a store that hasn't been defined yet, Alpine will throw an error, or the store will appear as undefined.

Namespacing for larger applications: For simple applications, one or two global stores might be fine. However, as your application grows, putting all global state into a single monolithic store can make it difficult to manage, debug, and understand. Consider creating multiple, focused stores. For example, instead of:

Alpine.store('app', {
  user: { name: 'Alice', loggedIn: true },
  cart: { items: [], total: 0 },
  settings: { theme: 'dark' }
});

Break it down into more manageable pieces:

Alpine.store('user', { name: 'Alice', loggedIn: true });
Alpine.store('cart', { items: [], total: 0 });
Alpine.store('settings', { theme: 'dark' });

This improves organization, making it easier to find relevant state and logic (e.g., $store.user.name, $store.cart.addItem()).