@ikas/popup-script-injector

@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: "[e-mail]",
    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)

• 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>
  

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

• 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.