Dev: Overview

What is WishlistHelper

WishlistHelper is a JavaScript helper for managing wishlists in Shopify storefronts. Once initialized, it is available globally at window.refactor_apps.wishlist and can be called from any storefront script.

The helper operates across two layers: local persistence via localStorage and cloud synchronization with the server. This means guest users can use the wishlist too — their data is stored in the browser and synced to the server upon login.

Key capabilities

List management. The helper supports multiple wishlist lists per user. Lists can be created and cleared, and product variants can be added to or removed from them individually.

Guest and authenticated users. The helper behaves differently depending on whether the user is logged in. For authenticated users, data is synced with the server. For guests, the helper works entirely with local storage. A forced server refresh can be triggered explicitly via the forceSync option.

Flow Triggers. When a variant is added or removed, the helper automatically dispatches events to Shopify Flow. Authenticated and guest users emit different flowHandle values, allowing you to build separate automations for each segment.

Architecture

The helper is loaded via an App Embed Extension in the Shopify theme editor and becomes available on every page of the activated theme. Initialization is asynchronous — always wait for await window.refactor_apps.wishlist.ready() before calling any other methods.

Do you need help?

If you have any questions or run into issues, please contact us — we’re happy to help.