@bagisto-native/core

@bagisto-native/core is the foundation module for Bagisto Native, enabling seamless communication between web applications and native applications using Hotwire technology.

It is built to work seamlessly with Open Source Headless eCommerce, and any React.js/Next.js setup allowing developers to connect a headless storefront with native mobile apps.

This module provides:

• Core Web Components for native interaction
• Hotwire bridge bundle (bundle.js)
• Utility functions for web ↔ native communication

Note: To create Bagisto Headless Commerce, use the following command:

npx -y @bagisto-headless/create your-storefront

📦 Installation

Install the module via npm:

npm install @bagisto-native/core

Note: This module must be used alongside @bagisto-native/react if you're using React/Next.js.

🛠️ Setup

1. Add the Hotwire Bridge Bundle

The Hotwire bridge bundle (bundle.js) is required for native communication.

Steps:

1. Navigate to node_modules/@bagisto-native/core/public
2. Copy bundle.js
3. Paste it into your project's public directory
4. Include it in your HTML:

<script src="/bundle.js"></script>

5. Or, include this as a static script in Next.js or similar frameworks.

🌐 Web Components

@bagisto-native/core provides the following Web Components:

| Component | Description | | -------------------- | ----------------------------------------------------------------- | | dynamic-button | Handles native buttons for cart (also cart count), share, barcode, and image search | | hotwire-toast | Trigger native toast messages | | hotwire-search | Trigger native search events | | hotwire-location | Auto-fill checkout address using native location | | hotwire-history-sync | Send current page URL and tab-title to native apps | | hotwire-theme-mode | Send current theme mode (light/dark) |

These components are primarily used in web projects but are wrapped by React components in @bagisto-native/react.

⚡ Usage Examples

Hotwire Toast

import '@bagisto-native/core';

<hotwire-toast style="display: none;"></hotwire-toast>

Trigger a toast using the triggerHotwireNativeToast(message: string) function.

import { triggerHotwireNativeToast } from '@bagisto-native/core';

triggerHotwireNativeToast('Hello World!');

Hotwire History Sync

import '@bagisto-native/core';

<hotwire-history-sync style="display: none;"></hotwire-history-sync>

Send current url and tab-title using the triggerHistorySyncEvent(url: URL, tabTitle: string) function.

import { triggerHistorySyncEvent } from '@bagisto-native/core';

triggerHistorySyncEvent(new URL('https://example.com'));

Hotwire Theme Mode

import '@bagisto-native/core';

<hotwire-theme-mode style="display: none;"></hotwire-theme-mode>

Send theme mode using the triggerThemeModeEvent(mode: 'light' | 'dark') function.

import { triggerThemeModeEvent } from '@bagisto-native/core';

triggerThemeModeEvent('light'); // 'light' or 'dark'

Hotwire Search

import '@bagisto-native/core';

<hotwire-search style="display: none;"></hotwire-search>

Listen to search events:

// Listen for a custom event from Turbo.
const handleTurboSearch = (e: Event) => {
    const customEvent = e as CustomEvent<{ query?: string; code?: string }>;
    const query = customEvent.detail.query || customEvent.detail.code;
    if (!query) return;
    router.push(`/search?q=${encodeURIComponent(query)}`);
};

window.addEventListener("turbo:next-search", handleTurboSearch);

Hotwire Location

import '@bagisto-native/core';

<hotwire-location style="display: none;"></hotwire-location>

Listen to location events:

// Listen for a custom event from Turbo.
const handleLocationEvent = (e: Event) => {
    const customEvent = e as CustomEvent<{ data: any }>;
    const data = customEvent.detail.data;
    console.log(data);

    // Here, data include the current address of the user's device.
};

window.addEventListener("turbo:hotwire-app-fill-addresses", handleLocationEvent);

Dynamic Button

import '@bagisto-native/core';

<dynamic-button data-page-type="home" style="display: none;"></dynamic-button>

Use pageType='home' on homepage, pageType='product' on product pages.

On both the home page and product page variants, the dynamic button component also shows the cart icon in the native app area. When we click on the cart icon, it emits the turbo:next-cart-modal event. You can open the cart modal or route to the cart page as per your requirement by listening to this event.

If you want to open the cart modal and also include the native modal close button on the screen, you can use the following configuration of DynamicButton:

<dynamic-button
  data-action="click->bridge--dynamicbutton#sendModalOpenEvent"
  style="display: none;"
>
</dynamic-button>

<dynamic-button
  data-action="click->bridge--dynamicbutton#sendModalDismissEvent"
  style="display: none;"
>
</dynamic-button>

Now, you also have to send the event to the native side of the application when you open the modal, and also send the event when you close the modal via external sources.

For sending the modal open event, use the following method:

import { triggerDynamicButtonModalOpenEvent } from '@bagisto-native/core';

triggerDynamicButtonModalOpenEvent();

For sending the modal dismiss event, use the following method:

import { triggerDynamicButtonModalDismissEvent } from '@bagisto-native/core';

triggerDynamicButtonModalDismissEvent();

However, without the native cart modal close icon, you can handle the cart modal or any other modal by only listening to the turbo:next-cart-modal event.

For using the cart count variant, you need to add the following configuration of DynamicButton:

<dynamic-button
  data-action="click->bridge--dynamicbutton#sendCartCount"
  style="display: none;"
>
</dynamic-button>

Now, whenever the cart count changes, you also need to notify the native app. For this, you can use the following method from @bagisto-native/core:

import { triggerCartCountValue } from '@bagisto-native/core';

triggerCartCountValue(5);

Dynamic Button Home Page Variant

It basically shows three icons on the home page. The first one is for the Image Search feature, the second one is for the Barcode/QR code feature, and the third one is for the Cart and cart count feature.

When you click on the Image Search icon or the Barcode/QR code icon, the corresponding native component opens and sends the processed data via the turbo:next-search event. You can listen to this event and handle the search process.

const handleTurboSearch = (e: Event) => {
    const customEvent = e as CustomEvent<{ query?: string; code?: string }>;
    const query = customEvent.detail.query || customEvent.detail.code;
    if (!query) return;
    window.location.href = `/search?q=${encodeURIComponent(query)}`;
};

window.addEventListener("turbo:next-search", handleTurboSearch);

Dynamic Button Product Page Variant

In this variant, the dynamic button component shows the product share icon and cart icon in the application’s native area. The cart icon works the same as in the home page variant of the dynamic button component. When you click on the product share icon, it will open the native share modal, and you can handle the share process.

Dynamic Button Emtpy Variant

When we use the home or product variant of the dynamic button and then navigate to the auth pages, the previous-page icon remains visible. To hide this icon on the auth pages, use the empty variant of the dynamic button.

<dynamic-button data-page-type="empty" style="display: none;"></dynamic-button>

⚡ Utility Functions

@bagisto-native/core provides several helper functions:

triggerHotwireNativeToast(message: string)

Trigger a native toast message (hotwire-toast component must be present in the DOM):

import { triggerHotwireNativeToast } from "@bagisto-native/core";

triggerHotwireNativeToast("Hello World!");

triggerHistorySyncEvent(url: URL, tabTitle: string)

Send the current URL and tab-title to the native app (hotwire-history-sync component must be present in the DOM):

import { triggerHistorySyncEvent } from "@bagisto-native/core";

const url = new URL(window.location.href);
const tabTitle = document?.title || "";
triggerHistorySyncEvent(url, tabTitle);

triggerThemeModeEvent(mode: "light" | "dark")

Send the current theme mode (hotwire-theme-mode component must be present in the DOM):

import { triggerThemeModeEvent } from "@bagisto-native/core";

triggerThemeModeEvent("light");

triggerCartCountValue(cartCount: number)

Send the cart count to the native app (the dynamic-button click->bridge--dynamicbutton#sendCartCount action variant must be present in the DOM):

import { triggerCartCountValue } from "@bagisto-native/core";

triggerCartCountValue(3);

isTurboNativeUserAgent(userAgent?: string): boolean

Check if the current environment is a Turbo Native app:

import { isTurboNativeUserAgent } from "@bagisto-native/core";

// Client-side
if (isTurboNativeUserAgent()) {
    console.log("Running in Turbo Native");
}

// Server-side
isTurboNativeUserAgent(req.headers['user-agent']);

triggerDynamicButtonModalOpenEvent()

Trigger a modal open event (the dynamic-button click->bridge--dynamicbutton#sendModalOpenEvent action variant must be present in the DOM):

import { triggerDynamicButtonModalOpenEvent } from "@bagisto-native/core";

triggerDynamicButtonModalOpenEvent();

triggerDynamicButtonModalDismissEvent()

Trigger a modal dismiss event (the dynamic-button click->bridge--dynamicbutton#sendModalDismissEvent action variant must be present in the DOM):

import { triggerDynamicButtonModalDismissEvent } from "@bagisto-native/core";

triggerDynamicButtonModalDismissEvent();

Build the Native iOS App

After completing the setup of Bagisto Native, you can proceed to build the native iOS application using the official open-source repository.

🔗 Bagisto Native iOS App:
https://github.com/SocialMobikul/BagistoNative_iOS

📋 Requirements

• Node.js >= 18
• Works with any web project; for React/Next.js, use @bagisto-native/react for wrappers

🆘 Support

Open an issue or discussion in the repository if you need help.

📄 License

MIT License