Bagisto Native Web Components for any JS framework (React, Next.js, Vue, etc.)
npm install @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:
>
> ``bash`
> npx -y @bagisto-headless/create your-storefront
>
Install the module via npm:
`bash`
npm install @bagisto-native/core
> Note: This module must be used alongside @bagisto-native/react if you're using React/Next.js.
The Hotwire bridge bundle (bundle.js) is required for native communication.
Steps:
1. Navigate to node_modules/@bagisto-native/core/public
2. Copy
3. Paste it into your project's directory
4. Include it in your HTML:
`html`
5. Or, include this as a static script in Next.js or similar frameworks.
@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.
`tsx
import '@bagisto-native/core';
`
Trigger a toast using the triggerHotwireNativeToast(message: string) function.
`ts
import { triggerHotwireNativeToast } from '@bagisto-native/core';
triggerHotwireNativeToast('Hello World!');
`
`tsx
import '@bagisto-native/core';
`
Send current url and tab-title using the triggerHistorySyncEvent(url: URL, tabTitle: string) function.
`ts
import { triggerHistorySyncEvent } from '@bagisto-native/core';
triggerHistorySyncEvent(new URL('https://example.com'));
`
`tsx
import '@bagisto-native/core';
`
Send theme mode using the triggerThemeModeEvent(mode: 'light' | 'dark') function.
`ts
import { triggerThemeModeEvent } from '@bagisto-native/core';
triggerThemeModeEvent('light'); // 'light' or 'dark'
`
`tsx
import '@bagisto-native/core';
`
Listen to search events:
`ts/search?q=${encodeURIComponent(query)}
// 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();
};
window.addEventListener("turbo:next-search", handleTurboSearch);
`
`tsx
import '@bagisto-native/core';
`
Listen to location events:
`ts
// 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);
`
`tsx
import '@bagisto-native/core';
`
> 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:
`tsx
style="display: none;"
>
style="display: none;"
>
`
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:
`tsx
import { triggerDynamicButtonModalOpenEvent } from '@bagisto-native/core';
triggerDynamicButtonModalOpenEvent();
`
For sending the modal dismiss event, use the following method:
`tsx
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:
`tsx`
style="display: none;"
>
Now, whenever the cart count changes, you also need to notify the native app. For this, you can use the following method from :
`tsx
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.
`tsx/search?q=${encodeURIComponent(query)}
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 = ;
};
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.
`ts`
@bagisto-native/core provides several helper functions:
Trigger a native toast message (hotwire-toast component must be present in the DOM):
`ts
import { triggerHotwireNativeToast } from "@bagisto-native/core";
triggerHotwireNativeToast("Hello World!");
`
Send the current URL and tab-title to the native app (hotwire-history-sync component must be present in the DOM):
`ts
import { triggerHistorySyncEvent } from "@bagisto-native/core";
const url = new URL(window.location.href);
const tabTitle = document?.title || "";
triggerHistorySyncEvent(url, tabTitle);
`
Send the current theme mode (hotwire-theme-mode component must be present in the DOM):
`ts
import { triggerThemeModeEvent } from "@bagisto-native/core";
triggerThemeModeEvent("light");
`
Send the cart count to the native app (the dynamic-button click->bridge--dynamicbutton#sendCartCount action variant must be present in the DOM):
`ts
import { triggerCartCountValue } from "@bagisto-native/core";
triggerCartCountValue(3);
`
Check if the current environment is a Turbo Native app:
`ts
import { isTurboNativeUserAgent } from "@bagisto-native/core";
// Client-side
if (isTurboNativeUserAgent()) {
console.log("Running in Turbo Native");
}
// Server-side
isTurboNativeUserAgent(req.headers['user-agent']);
`
Trigger a modal open event (the dynamic-button click->bridge--dynamicbutton#sendModalOpenEvent action variant must be present in the DOM):
`ts
import { triggerDynamicButtonModalOpenEvent } from "@bagisto-native/core";
triggerDynamicButtonModalOpenEvent();
`
Trigger a modal dismiss event (the dynamic-button click->bridge--dynamicbutton#sendModalDismissEvent action variant must be present in the DOM):
`ts
import { triggerDynamicButtonModalDismissEvent } from "@bagisto-native/core";
triggerDynamicButtonModalDismissEvent();
`
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
* Node.js >= 18
* Works with any web project; for React/Next.js, use @bagisto-native/react` for wrappers
Open an issue or discussion in the repository if you need help.
MIT License