Skip to content

Shared State (Pinia)

Each Vue island is its own app, but they can share reactive state through a single page-wide Pinia instance. This is opt-in by design: Pinia loads only when a component imports a store. The island bootstrap then installs that shared instance on the islands — but a page where no component uses a store ships no Pinia at all.

A store module activates the shared instance on import (via ensureSharedPinia()), and because every store resolves against the same active Pinia, any islands that import it share state. Native ESM, pay-per-use.

Requirement: stores import pinia, so the theme must expose it in exposeNpmPackages (see JS Configuration). If a store is imported without Pinia exposed, the build fails loudly.

Authoring a shared store

Call ensureSharedPinia() at the top of your store module, then define stores as usual:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { defineStore } from 'pinia';
import { ensureSharedPinia } from 'MageObsidian_ModernFrontend::js/store';

ensureSharedPinia();

export const useUiStore = defineStore('ui', {
    state: () => ({ cartDrawerOpen: false }),
    actions: {
        toggleCartDrawer() {
            this.cartDrawerOpen = !this.cartDrawerOpen;
        },
    },
});

Two different islands — say a header cart button and a cart drawer — that both import { useUiStore } now read and write the same state.

The customer-data bridge

useCustomerData is a ready-made store that mirrors Magento's private content (the customer-data sections: cart, customer, wishlist, compare-products, …) into reactive state:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<script setup>
import { computed } from 'vue';
import { useCustomerData } from 'MageObsidian_ModernFrontend::js/customer-data';

const customerData = useCustomerData();
const cartCount = computed(() => customerData.section('cart')?.summary_count ?? 0);
</script>

<template>
    <span class="cart-count">{{ cartCount }}</span>
</template>

It is read-mostly: Magento's native customer-data.js stays the owner of the canonical store (localStorage['mage-cache-storage']) and the /customer/section/load/ endpoint. The bridge reads that cache, re-syncs when Magento broadcasts an update, and exposes reload() for an explicit refresh — so it never breaks Full Page Cache.

Member Purpose
sections Reactive map of all sections.
section(name) A single section, or null.
sync() Re-read the canonical store (called automatically on Magento updates).
reload(names = [], { force }) Fetch sections from /customer/section/load/ and merge.
patch(name, partial) Merge a partial section into the reactive map, in memory only.
snapshot() The current map, to go back to.
restore(snapshot) Put it back.

Projecting a change before the server confirms it

patch exists so an interaction can show its result immediately instead of waiting out the round trip — bumping summary_count the moment an add-to-cart is submitted, dropping a row the moment its trash icon is clicked.

It is deliberately memory-only: it never writes to mage-cache-storage. Magento's customer-data.js remains the owner of the canonical cache, so a projection that turns out to be wrong dies with the page rather than outliving it in local storage. snapshot() and restore() are the pair that undoes one when the server refuses:

1
2
3
4
5
6
const rollback = customerData.snapshot();
customerData.patch('cart', { summary_count: count.value + qty });

if (!(await addToCart()).ok) {
    customerData.restore(rollback);
}

A flow that reloads the section afterwards needs no rollback at all — the reload overwrites the projection with the truth. See Optimistic UI & Motion for the full pattern and the admin flag that governs it.

How it stays FPC-safe

Magento serves cached pages and loads private content client-side after render (via /customer/section/load/, a never-cached endpoint), so per-user data is never baked into the cached HTML. The bridge observes that flow instead of fighting it: it reads mage-cache-storage, subscribes to Magento's update broadcasts, and only the explicit reload() ever hits the network.

Next Steps