Basic Stores

WildflowerJS stores provide global state management using the same unified entity model as components, plugins, and pool entities.

Stores share one model with the rest of the framework. Stores, components, plugins, and pool entities all share the same foundational architecture. They're all reactive entities with state, computed properties, methods, and lifecycle hooks. The key difference is that stores exist without DOM elements, making them ideal for global application state.

The Unified Entity Model

In WildflowerJS, stores and components are remarkably similar. Both support:

Component

wildflower.component('counter', {
    state: { count: 0 },

    computed: {
        doubled() {
            return this.count * 2
        }
    },

    increment() {
        this.count++
    },

    init() {
        // Lifecycle hook
    }
})

Store

wildflower.store('counter', {
    state: { count: 0 },

    computed: {
        doubled() {
            return this.count * 2
        }
    },

    increment() {
        this.count++
    },

    init() {
        // Lifecycle hook
    }
})

The only differences are:

Registration method: wildflower.component() vs wildflower.store()
DOM binding: Components bind to DOM elements; stores don't
Scope: Components are local to their DOM; stores are global singletons

Once you understand component patterns (state, computed, methods, lifecycle), you already know how to write stores. The same mental model applies throughout the framework.

Creating Stores

Use wildflower.store() to create global state stores that components can read and write:

                        // Create a comprehensive counter store with advanced features
wildflower.store('counter', {
    state: {
        count: 0,
        step: 1,
        autoIncrement: false,
        incrementInterval: null
    },

    computed: {
        doubleCount() {
            return this.count * 2
        },

        isPositive() {
            return this.count > 0
        },

        isNegative() {
            return this.count < 0
        },

        magnitude() {
            return Math.abs(this.count)
        },

        status() {
            if (this.count === 0) return 'zero'
            if (this.count > 0) return 'positive'
            return 'negative'
        },

        progressPercentage() {
            // Calculate percentage for values -100 to +100
            return Math.max(0, Math.min(100, ((this.count + 100) / 200) * 100))
        }
    },

    // Methods (unified paradigm - at top level, not in actions block)
    increment() {
        this.count += this.step
    },

    decrement() {
        this.count -= this.step
    },

    reset() {
        this.count = 0
    },

    setStep(newStep) {
        const validStep = Math.max(1, Math.min(50, parseInt(newStep) || 1))
        this.step = validStep
    },

    setCount(newCount) {
        this.count = parseInt(newCount) || 0
    },

    toggleAutoIncrement() {
        this.autoIncrement = !this.autoIncrement

        if (this.autoIncrement) {
            this.incrementInterval = setInterval(() => {
                this.increment()
            }, 1000)
        } else {
            if (this.incrementInterval) {
                clearInterval(this.incrementInterval)
                this.incrementInterval = null
            }
        }
    },

    // Store lifecycle
    destroy() {
        if (this.incrementInterval) {
            clearInterval(this.incrementInterval)
        }
    }
})
                    

                        <div data-component="counter-display">
    <p class="text-muted">Demonstrates global state management with WildflowerJS stores.</p>

    <div class="row">
        <div class="col-md-6">
            <!-- Counter Display -->
            <div class="card mb-3">
                <div class="card-body text-center">
                    <h1 data-bind="$counter.count"
                        data-bind-class="$counter.status === 'positive' ? 'text-success' : $counter.status === 'negative' ? 'text-danger' : 'text-secondary'">0</h1>

                    <div class="row text-center mt-3">
                        <div class="col-4">
                            <small class="text-muted">Double</small>
                            <div data-bind="$counter.doubleCount" class="fw-bold"></div>
                        </div>
                        <div class="col-4">
                            <small class="text-muted">Step</small>
                            <div data-bind="$counter.step" class="fw-bold"></div>
                        </div>
                        <div class="col-4">
                            <small class="text-muted">Magnitude</small>
                            <div data-bind="$counter.magnitude" class="fw-bold"></div>
                        </div>
                    </div>

                    <!-- Progress Bar -->
                    <div class="mt-3">
                        <small class="text-muted">Range: -100 to +100</small>
                        <div class="progress mt-1" style="height: 12px;">
                            <div class="progress-bar"
                                 data-bind-class="counterProgressColorClass"
                                 data-bind-style="{ width: $counter.progressPercentage + '%' }">
                            </div>
                        </div>
                    </div>
                </div>
            </div>

            <!-- Control Buttons -->
            <div class="d-grid gap-2">
                    <button data-action="increment" class="btn btn-success">
                        + <span data-bind="$counter.step"></span>
                    </button>
                    <button data-action="decrement" class="btn btn-danger">
                        - <span data-bind="$counter.step"></span>
                    </button>

                    <button data-action="reset" class="btn btn-secondary">Reset to 0</button>
                    <button data-action="toggleAutoIncrement"
                            data-bind-class="$counter.autoIncrement ? 'btn btn-warning' : 'btn btn-outline-primary'">
                        <span data-bind="$counter.autoIncrement ? 'Stop Auto' : 'Start Auto'"></span>
                    </button>
            </div>
        </div>

        <div class="col-md-6">
            <!-- Configuration -->
            <div class="card mb-3">
                <div class="card-header">
                    <h6 class="mb-0">Configuration</h6>
                </div>
                <div class="card-body">
                    <div class="mb-3">
                        <label class="form-label">Step Size (1-50):</label>
                        <input type="number" data-model="localStep" data-action="input:updateStep"
                               class="form-control" min="1" max="50" placeholder="Enter step size">
                    </div>

                    <div class="mb-3">
                        <label class="form-label">Set Count Directly:</label>
                        <input type="number" data-model="directCount" class="form-control mb-2"
                               placeholder="Enter count value">
                        <button data-action="setDirectCount" class="btn btn-primary">Set</button>
                    </div>

                    <div class="d-flex justify-content-between align-items-center">
                        <span>Auto-increment:</span>
                        <span data-bind="$counter.autoIncrement ? '🟢 ON' : '⚪ OFF'"
                              data-bind-class="$counter.autoIncrement ? 'text-success' : 'text-muted'"></span>
                    </div>
                </div>
            </div>
        </div>
    </div>
</div>
                    

                        wildflower.component('counter-display', {
    state: {
        localStep: 1,
        directCount: ''
    },

    // Declarative store subscription - enables this.stores.counter
    subscribe: {
        counter: ['count', 'step']
    },

    // Initialize local state from store (this.stores is available)
    init() {
        this.localStep = this.stores.counter.step
    },

    // React to store changes with centralized logic
    onStoreUpdate(storeName, path, newValue, oldValue) {
        if (storeName === 'counter' && path === 'step') {
            this.localStep = newValue
        }
    },

    // Actions use this.stores shorthand
    increment() {
        this.stores.counter.increment()
    },

    decrement() {
        this.stores.counter.decrement()
    },

    reset() {
        this.stores.counter.reset()
    },

    toggleAutoIncrement() {
        this.stores.counter.toggleAutoIncrement()
    },

    updateStep() {
        this.stores.counter.setStep(this.localStep)
    },

    setDirectCount() {
        if (this.directCount !== '') {
            this.stores.counter.setCount(this.directCount)
            this.directCount = '' // Clear input after setting
        }
    },

    computed: {
        counterProgressColorClass() {
            const status = this.stores.counter.status
            if (status === 'positive') return 'bg-success'
            if (status === 'negative') return 'bg-danger'
            return 'bg-secondary'
        }
    }
})
                    

Live Preview

Store Architecture

Stores are implemented as virtual components that integrate with the framework's reactivity system:

Virtual Component Design:

Stores exist in the component system without DOM elements
Protected from garbage collection via isVirtual: true flag
Full component capabilities: state, computed, actions, lifecycle (init, destroy, tick)
Automatic dependency tracking between stores and components
tick(dt) enables headless animation: the store drives updates each frame via requestAnimationFrame
destroy() provides lifecycle cleanup for releasing resources, clearing intervals, etc.

Declarative Store Subscriptions (`subscribe`)

The recommended way to connect components to stores is using the declarative subscribe block. This enables automatic store injection via this.stores and triggers onStoreUpdate() when subscribed paths change:

wildflower.component('dashboard-widget', {
    state: {
        userName: '',
        cartCount: 0
    },

    // Declare which stores and paths to subscribe to
    subscribe: {
        user: ['profile', 'preferences'],  // Subscribe to user.profile and user.preferences
        cart: ['items']                     // Subscribe to cart.items
    },

    init() {
        // this.stores is auto-injected based on subscribe block
        this.userName = this.stores.user.profile?.name || 'Guest'
        this.cartCount = this.stores.cart.items?.length || 0
    },

    // Called when ANY subscribed path changes
    onStoreUpdate(storeName, path, newValue, oldValue) {
        if (storeName === 'user' && path === 'profile') {
            this.userName = newValue?.name || 'Guest'
        } else if (storeName === 'cart' && path === 'items') {
            this.cartCount = newValue?.length || 0
        }
    },

    // Use this.stores throughout your component
    updatePreferences(prefs) {
        this.stores.user.updatePreferences(prefs)
    },

    addToCart(item) {
        this.stores.cart.addItem(item)
    }
})

Benefits of Declarative Subscriptions:

this.stores shorthand - No more wildflower.getStore() calls
onStoreUpdate() hook - Centralized handling of store changes
Automatic cleanup - Subscriptions are removed when component is destroyed
Clear dependencies - Easy to see which stores a component uses

The `this.stores` Shorthand

When you declare a subscribe block, the framework automatically injects store references into this.stores. This is available in init(), all methods, and computed properties:

wildflower.component('store-profile', {
    subscribe: {
        auth: ['user', 'token'],
        cart: ['items']
    },

    computed: {
        // For simple display, prefer $ in HTML instead:
        // data-bind="$auth.user.name", data-bind="$auth.isAuthenticated"
        // Use this.stores when you need JS transformation:
        currentUser() {
            return this.stores.auth.user
        },

        isLoggedIn() {
            return this.stores.auth.isAuthenticated
        },

        cartItemCount() {
            return this.stores.cart.totalItems
        }
    },

    // Use this.stores in methods
    logout() {
        this.stores.auth.logout()
    },

    addToCart(product) {
        this.stores.cart.addItem(product)
    }
})

Important: this.stores is ONLY available in components that declare a subscribe block. Without subscribe, use wildflower.getStore('name') instead:

// Without subscribe: use getStore() (auto-reactive in computed)
wildflower.component('simple-widget', {
    computed: {
        revenue() { return wildflower.getStore('metrics').revenue; }
    }
});

// With subscribe: this.stores available
wildflower.component('reactive-widget', {
    subscribe: { metrics: ['revenue'] },
    computed: {
        revenue() { return this.stores.metrics.revenue; }
    }
});

The `onStoreUpdate()` Hook

The onStoreUpdate() lifecycle hook is called whenever a subscribed store path changes. It receives full context about the change:

wildflower.component('notification-badge', {
    state: { count: 0 },

    subscribe: {
        notifications: ['unread']
    },

    // Called when notifications.unread changes
    onStoreUpdate(storeName, path, newValue, oldValue) {
        // storeName: 'notifications'
        // path: 'unread'
        // newValue: the new array/value
        // oldValue: the previous array/value

        if (storeName === 'notifications' && path === 'unread') {
            this.count = newValue?.length || 0

            // Play sound if new notifications added
            if (newValue?.length > (oldValue?.length || 0)) {
                this.playNotificationSound()
            }
        }
    },

    playNotificationSound() {
        // ...
    }
})

The Readiness Wait (`subscribeTimeout`)

A component with a subscribe block holds its init() until every subscribed store is ready, so init-time code can assume this.stores is populated. The wait is bounded: 5000ms by default, configurable per component with subscribeTimeout in the definition, or globally with wildflower.config({ subscribeTimeout: 10000 }). A value of 0 waits indefinitely.

wildflower.component('dashboard', {
    subscribe: ['session'],
    subscribeTimeout: 10000,   // this component tolerates a slow session store
    init() { /* this.stores.session is ready here */ }
});

When the window runs out, the component's onError hook receives the timeout and init proceeds best-effort (WF-910), so a slow store degrades the component instead of hanging it. A subscribed name that is never registered at all fails fast rather than running out the window (WF-909), which keeps a typo from masquerading as a slow store.

Accessing Store Data

There are multiple ways to access store data. The subscribe + this.stores pattern is recommended for most use cases:

Method	Use Case	Auto-cleanup
`subscribe` + `this.stores`	Recommended for JS - Clean, declarative, with change notifications	Yes
`$storeName.path`	Recommended for HTML - Direct store binding in templates	N/A
`wildflower.getStore()`	One-off access, outside components, or without subscriptions	N/A
`external()`	Legacy: prefer `$entityName.path` in HTML	N/A

Using `wildflower.getStore()`

For components that don't need subscriptions, or for accessing stores outside of components:

wildflower.component('simple-display', {
    computed: {
        // Still works - automatically reactive in computed properties
        currentUser() {
            return wildflower.getStore('auth').user
        }
    },

    // In methods, getStore() is useful for one-off access
    logout() {
        wildflower.getStore('auth').logout()
    }
})

Automatic Dependency Tracking: When a component's computed property reads store data via getStore() or this.stores, the framework automatically:

Detects which store properties are accessed
Registers the component as a dependent of that store
Re-evaluates the computed property when store data changes

Using `$entityName.path` in HTML

For direct binding to any entity (store, component, or plugin) in HTML templates, use the $ accessor:

<!-- Bind directly to store state -->
<span data-bind="$user.name"></span>

<!-- Use in conditionals -->
<div data-show="$auth.isLoggedIn">
    Welcome back!
</div>

<!-- Store-backed lists -->
<div data-list="$cart.items" data-key="id">
    <template>
        <div data-bind="name"></div>
    </template>
</div>

<!-- Nested paths -->
<span data-bind="$auth.user.address.city"></span>

<!-- In expressions -->
<div data-show="$cart.items.length > 0">Cart is not empty</div>

Universal Accessor: $entityName.path works for stores, components, and plugins. It's the universal way to access any entity's state or computed properties in HTML templates. Computed properties resolve automatically (no computed: prefix needed).

Continue Learning: For advanced store patterns including store-to-store communication, persistence, lifecycle management, and the complete API reference, see Advanced Store Patterns.

Lite Analytics Dashboard

Several stores driving real-time chart updates, computed metrics, and theme switching across one page.

Demo Code

Previous Pool Performance

Next Advanced Store Patterns

Basic Stores

The Unified Entity Model

Creating Stores

Store Architecture

Declarative Store Subscriptions (subscribe)

The this.stores Shorthand

The onStoreUpdate() Hook

The Readiness Wait (subscribeTimeout)