Skip to main content

📦 Installation

This guide walks you through installing and configuring the Alphabite Wishlist Plugin in your Medusa backend.

1. Install the Plugin​

Install the package via npm:

npm install @alphabite/medusa-wishlist

2. Register the Plugin​

Add the plugin to your medusa.config.ts or medusa-config.js:

import { WishlistPluginOptions } from "@alphabite/medusa-wishlist";

export default {
  plugins: [
    {
      resolve: "@alphabite/medusa-wishlist",
      options: {
        allowGuestWishlist: true,
        includeWishlistItems: true,
        shareTokenSecret: "your_custom_secret",
      } satisfies WishlistPluginOptions,
    },
  ],
};

3. Run Database Migrations​

The plugin adds new tables to support wishlists. Run the migration after registration:

npx medusa migration run

4. Plugin Options​

OptionTypeDefaultDescription
allowGuestWishlistbooleanfalseEnables session-based wishlist for guests
includeWishlistItemsbooleanfalseAutomatically includes items when listing wishlists
includeWishlistItemsTakenumber5Limits number of items returned per wishlist (when includeWishlistItems is true)
wishlistFieldsstring[][]Controls which wishlist fields are returned in API responses
wishlistItemsFieldsstring[]"id", "product_id", "wishlist_id", "created_at", "updated_at", "deleted_at", "product_variant.*", "product_variant.prices.*", "product_variant.calculated_price", "product_variant.product.thumbnail",Controls which wishlist item fields are returned
shareTokenSecretstring"default_secret"Used to sign export/import tokens

5. Environment Variables (Optional)​

You can use environment variables for the secret key if preferred:

shareTokenSecret: process.env.WISHLIST_SHARE_SECRET || "fallback_secret";

✅ Compatibility​

  • Requires Medusa v2
  • Adds database tables (migration required)
  • Compatible with both JS and TypeScript projects

🚀 Next Step​

👉 Explore the REST API