@ikas/popup-widget

Standalone popup widget renderer extracted from the storefront codebase. It can be consumed as a plain <script> bundle or as a React component inside Next/React applications.

Building

# install workspace dependencies first (from repo root)
npm install

# then build the widget bundle
npm run build --workspace @ikas/popup-widget

The build command produces three artefacts under dist/:

• popup-widget.es.js
• popup-widget.cjs.js
• popup-widget.iife.js – automatically calls startIkasPopupWidget() after loading and registers a global IkasPopupWidget namespace.

Source maps are emitted for all formats.

Configuration Shape

The widget expects its configuration under window.ikasPopupConfig. The runtime type is exported as PopupWidgetConfig:

import type { PopupWidgetConfig } from "@ikas/popup-widget";

const exampleConfig: PopupWidgetConfig = {
  popups: [], // fill with IkasStorefrontPopup objects returned by your API
  sessionId: "session-123",
  locale: "en",
  countryCode: "US",
  merchantId: "merchant-id",
  cdnUrl: "https://cdn.myikas.dev/",
  storeUrl: "https://demo.myikas.dev",
  customerToken: undefined,
  priceListId: "price-list-id",
  salesChannelId: "sales-channel-id",
  customer: {
    email: "[email protected]",
    firstName: "Jane",
    lastName: "Doe",
  },
  services: {
    searchProducts: async () => [],
    addItemToCart: async () => ({ success: true }),
    saveCustomerFormData: async () => {},
    getLastViewedProducts: async () => [],
    formatVariantSellPrice: () => "₺0,00",
    formatVariantDiscountPrice: () => null,
    hasVariantDiscount: () => false,
    getVariantDiscountPercentage: () => null,
  },
};

Populate all relevant fields before loading the script.

Browser Usage (no framework)

1. Populate window.ikasPopupConfig before loading the bundle:

   import type { PopupWidgetConfig } from "@ikas/popup-widget";
   
   const ikasPopupConfig: PopupWidgetConfig = {
     popups: [], // fill with IkasStorefrontPopup objects
     sessionId: "session-123", // used for localStorage tracking
     locale: "en",
     countryCode: "US",
     merchantId: "merchant-id",
     cdnUrl: "https://cdn.myikas.dev/",
     storeUrl: "https://demo.myikas.dev",
     customerToken: undefined, // optional
     priceListId: "price-list-id",
     salesChannelId: "sales-channel-id",
     services: {
       searchProducts: async (params) => {
         console.log("search products", params);
         return [];
       },
       addItemToCart: async ({ product, variant }) => {
         console.log("add to cart", product, variant);
         return { success: true };
       },
       saveCustomerFormData: async (payload) => {
         console.log("save customer", payload);
       },
       getLastViewedProducts: async () => {
         return [];
       },
       formatVariantSellPrice: () => "₺0,00",
       formatVariantDiscountPrice: () => null,
       hasVariantDiscount: () => false,
       getVariantDiscountPercentage: () => null,
     },
   };
   
   window.ikasPopupConfig = ikasPopupConfig;

   <link
     rel="stylesheet"
     href="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css"
   />
   <script src="./dist/popup-widget.iife.js" defer></script>

2. Provide the service implementations so the widget can delegate cart operations, customer form submissions and dynamic product fetching back to your storefront.

3. The IIFE build bootstraps itself once the script executes. When using the ES/CJS bundles you can call startIkasPopupWidget() manually:

   import { startIkasPopupWidget } from "@ikas/popup-widget";
   
   startIkasPopupWidget(window.ikasPopupConfig);

React / Next Usage

import dynamic from "next/dynamic";

const PopupListRendererForPage = dynamic(() =>
  import("@ikas/popup-widget").then((mod) => mod.PopupListRendererForPage),
  { ssr: false }
);

// … inside component tree
<PopupListRendererForPage />;

The startIkasPopupWidget helper can also be called from React apps if you want an imperative bootstrap (e.g. outside of the main React tree).

Known Gaps / TODO

• Type declaration emission is not wired (no dist/*.d.ts). We should add a tsc build step or rollup-plugin-dts before publishing.
• You must provide window.ikasPopupConfig.popups. No automatic fetch from the storefront API is performed.

These items are tracked as follow-up tasks before we deprecate the original packages/storefront/src/components/popup implementation.