@dutchiesdk/ecommerce-extensions-sdk 0.16.0 → 0.17.0

package/README.md

@@ -191,6 +191,220 @@ const currentLocations = await dataLoaders.locations(); // Current context locat
 
 You can register callback functions that will be triggered by certain events in the Dutchie platform in your extension's `RemoteModuleRegistry` object.
 
+## Meta Fields Function
+
+### Overview
+
+The `getStoreFrontMetaFields` function is the **recommended approach** for generating page metadata (title tags, meta descriptions, Open Graph tags, etc.) in your theme. This function-based approach replaces the `StoreFrontMeta` component pattern.
+
+**Why use this approach:**
+
+- ✅ **Full data access** - Direct access to data loaders (products, categories, etc.)
+- ✅ **Async support** - Make API calls to fetch data for dynamic meta tags
+- ✅ **Centralized control** - Single function handles all page metadata logic
+- ✅ **Better performance** - Called once per navigation, not re-rendered on state changes
+
+> **🚀 Rollout Status:** The Dutchie platform is currently rolling out support for `getStoreFrontMetaFields` via a feature flag. During the transition period:
+>
+> - When the flag is **enabled**: Your `getStoreFrontMetaFields` function will be used (recommended)
+> - When the flag is **disabled**: The legacy `StoreFrontMeta` component will be used
+> - Both implementations can coexist in your theme during migration
+> - The component approach will be deprecated once the rollout is complete
+
+> **Note:** When you provide `getStoreFrontMetaFields` and the feature flag is enabled, the `StoreFrontMeta` component will not be used. We recommend implementing the function approach now to prepare for the full migration
+
+### Function Signature
+
+```typescript
+export type StoreFrontMetaFieldsFunction = (
+  data: CommerceComponentsDataInterface
+) => MetaFields | Promise<MetaFields>;
+```
+
+The function receives the full data bridge interface and can return meta fields synchronously or asynchronously.
+
+### Meta Fields Type
+
+```typescript
+type MetaFields = {
+  title?: string; // Page title
+  description?: string; // Meta description
+  ogImage?: string; // Open Graph image URL
+  canonical?: string; // Canonical URL
+  structuredData?: Record<string, any>; // JSON-LD structured data
+  customMeta?: Array<{
+    // Additional meta tags
+    name?: string;
+    property?: string;
+    content: string;
+  }>;
+};
+```
+
+### Implementation
+
+Create a file in your theme (e.g., `get-meta-fields.ts`):
+
+```typescript
+import {
+  CommerceComponentsDataInterface,
+  MetaFields,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+export const getStoreFrontMetaFields = async (
+  data: CommerceComponentsDataInterface
+): Promise<MetaFields> => {
+  const { location, dataLoaders } = data;
+  const page = typeof window !== "undefined" ? window.location.pathname : "";
+
+  // Access data loaders for dynamic content
+  const product = await dataLoaders.product();
+  const categories = await dataLoaders.categories();
+
+  // Generate page-specific metadata
+  let pageTitle = location?.name || "Shop Cannabis";
+  let pageDescription = `Browse our selection at ${location?.name}`;
+
+  if (product) {
+    pageTitle = `${product.name} | ${location?.name}`;
+    pageDescription = `${product.description?.substring(0, 155)}...`;
+  }
+
+  return {
+    title: pageTitle,
+    description: pageDescription,
+    ogImage: location?.images?.logo,
+    canonical: `${location?.links?.storeFrontRoot}${page}`,
+    structuredData: {
+      "@context": "https://schema.org",
+      "@type": "WebPage",
+      name: pageTitle,
+      description: pageDescription,
+    },
+    customMeta: [
+      {
+        name: "robots",
+        content: "index, follow",
+      },
+    ],
+  };
+};
+```
+
+### Register in Module Registry
+
+Add the function to your theme's `index.tsx`:
+
+```typescript
+import { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { getStoreFrontMetaFields } from "./get-meta-fields";
+
+export default {
+  StoreFrontHeader: createLazyRemoteBoundaryComponent(() => import("./header")),
+  StoreFrontFooter: createLazyRemoteBoundaryComponent(() => import("./footer")),
+  getStoreFrontMetaFields, // Register the function
+} satisfies RemoteModuleRegistry;
+```
+
+### Available Data
+
+The function receives the full `CommerceComponentsDataInterface`:
+
+```typescript
+{
+  menuContext: 'store-front' | 'kiosk',
+  location?: Dispensary,
+  user?: User,
+  cart?: Cart,
+  dataLoaders: {
+    product: () => Promise<Product | null>,
+    products: () => Promise<Product[]>,
+    categories: () => Promise<Category[]>,
+    // ... other loaders
+  },
+  actions: {
+    // Navigation and cart actions
+  }
+}
+```
+
+### Example Use Cases
+
+**Product Pages:**
+
+```typescript
+const product = await dataLoaders.product();
+if (product) {
+  return {
+    title: `${product.name} - ${location?.name}`,
+    description: product.description,
+    ogImage: product.images?.[0]?.url,
+    structuredData: {
+      "@context": "https://schema.org",
+      "@type": "Product",
+      name: product.name,
+      description: product.description,
+      offers: {
+        "@type": "Offer",
+        price: product.variants?.[0]?.priceRec,
+        priceCurrency: "USD",
+      },
+    },
+  };
+}
+```
+
+**Category Pages:**
+
+```typescript
+const categories = await dataLoaders.categories();
+const pathname = window.location.pathname;
+const categorySlug = pathname.split("/").pop();
+const category = categories.find((c) => c.slug === categorySlug);
+
+if (category) {
+  return {
+    title: `${category.name} | ${location?.name}`,
+    description: `Shop ${category.name} products at ${location?.name}`,
+  };
+}
+```
+
+**Home Page:**
+
+```typescript
+if (pathname === "/" || pathname === "") {
+  return {
+    title: `${location?.name} - Cannabis Dispensary`,
+    description: `Shop cannabis products online at ${location?.name}`,
+    structuredData: {
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      name: location?.name,
+      url: location?.links?.storeFrontRoot,
+      logo: location?.images?.logo,
+    },
+  };
+}
+```
+
+### Notes
+
+- The function is called on every page navigation
+- Async operations (like `dataLoaders.product()`) are supported
+- Return values are rendered into `<head>` tags automatically
+- The title tag will update dynamically as meta fields load
+- All fields are optional - return only what's needed for each page
+
+### Migration Strategy
+
+If you have an existing theme using the `StoreFrontMeta` component:
+
+1. **Implement the function**: Add `getStoreFrontMetaFields` to your theme's module registry
+2. **Test both approaches**: Keep your existing `StoreFrontMeta` component during the transition
+3. **Feature flag controls behavior**: Dutchie's feature flag determines which implementation is used
+4. **Future-proof**: Once the rollout completes, only the function approach will be supported
+
 ## Best Practices
 
 ### Data Loading
@@ -203,7 +417,7 @@ const MyComponent = () => {
   const { data, isLoading } = useAsyncLoader(dataLoaders.products);
 
   if (isLoading) return <LoadingSpinner />;
-  if (!data) return <EmptyProducts message="No products found" />;
+  if (!data) return <EmptyProducts message='No products found' />;
 
   return <ProductList products={data} />;
 };
@@ -249,7 +463,7 @@ const UserProfile = () => {
 
   if (!user) {
     return (
-      <div className="login-prompt">
+      <div className='login-prompt'>
         <p>Please log in to view your profile</p>
         <button onClick={actions.goToLogin}>Login</button>
       </div>
@@ -257,7 +471,7 @@ const UserProfile = () => {
   }
 
   return (
-    <div className="user-profile">
+    <div className='user-profile'>
       <h2>Welcome, {user.firstName}!</h2>
       {/* Profile content */}
     </div>

package/dist/context/ecommerce-data-bridge.cjs

@@ -30,7 +30,7 @@ __webpack_require__.d(__webpack_exports__, {
     useDataBridge: ()=>useDataBridge
 });
 const external_react_namespaceObject = require("react");
-const DataBridgeVersion = '0.16.0';
+const DataBridgeVersion = '0.17.0';
 const DataBridgeContext = (0, external_react_namespaceObject.createContext)(void 0);
 const useDataBridge = ()=>{
     const context = (0, external_react_namespaceObject.useContext)(DataBridgeContext);

package/dist/esm/context/ecommerce-data-bridge.js

@@ -1,5 +1,5 @@
 import { createContext, useContext, useEffect, useState } from "react";
-const DataBridgeVersion = '0.16.0';
+const DataBridgeVersion = '0.17.0';
 const DataBridgeContext = createContext(void 0);
 const useDataBridge = ()=>{
     const context = useContext(DataBridgeContext);

package/dist/esm/types/ecommerce-extension.d.ts

@@ -1,5 +1,6 @@
 import type React from 'react';
 import type { Events } from './events';
+import type { CommerceComponentsDataInterface } from './interface';
 export type RemoteBoundaryComponent<P = {}> = React.FC<P> & {
     DataBridgeVersion: string;
 };
@@ -7,6 +8,36 @@ export type RoutablePageRegistryEntry = {
     component: RemoteBoundaryComponent;
     path: string;
 };
+/**
+ * Meta fields for page metadata (SEO, social sharing, etc.)
+ */
+export type MetaFields = {
+    /** Page title (rendered in <title> tag) */
+    title?: string;
+    /** Page description (rendered in <meta name="description"> tag) */
+    description?: string;
+    /** Open Graph image URL */
+    ogImage?: string;
+    /** Canonical URL */
+    canonical?: string;
+    /** JSON-LD structured data for rich snippets */
+    structuredData?: Record<string, any>;
+    /** Additional custom meta tags */
+    customMeta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+};
+/**
+ * Function that returns meta fields for the current page.
+ * Receives the data bridge context as a parameter, allowing access to
+ * data loaders, cart, user, location, and actions.
+ *
+ * @param data - The commerce components data interface with loaders and state
+ * @returns Meta fields for the current page (title, description, OG tags, etc.)
+ */
+export type StoreFrontMetaFieldsFunction = (data: CommerceComponentsDataInterface) => MetaFields | Promise<MetaFields>;
 export type RemoteModuleRegistry = {
     RouteablePages?: RoutablePageRegistryEntry[];
     StoreFrontHeader?: RemoteBoundaryComponent;
@@ -17,5 +48,13 @@ export type RemoteModuleRegistry = {
     StoreFrontHero?: RemoteBoundaryComponent;
     ProductDetailsMeta?: RemoteBoundaryComponent;
     ProductDetailsPrimary?: RemoteBoundaryComponent;
+    /**
+     * Function that provides meta fields for the current page.
+     * Replaces the StoreFrontMeta component approach.
+     *
+     * Called by the host app with the full data bridge context:
+     * `const metaFields = registry.getStoreFrontMetaFields?.(dataBridgeData)`
+     */
+    getStoreFrontMetaFields?: StoreFrontMetaFieldsFunction;
     events?: Events;
 };

package/dist/types/ecommerce-extension.d.ts

@@ -1,5 +1,6 @@
 import type React from 'react';
 import type { Events } from './events';
+import type { CommerceComponentsDataInterface } from './interface';
 export type RemoteBoundaryComponent<P = {}> = React.FC<P> & {
     DataBridgeVersion: string;
 };
@@ -7,6 +8,36 @@ export type RoutablePageRegistryEntry = {
     component: RemoteBoundaryComponent;
     path: string;
 };
+/**
+ * Meta fields for page metadata (SEO, social sharing, etc.)
+ */
+export type MetaFields = {
+    /** Page title (rendered in <title> tag) */
+    title?: string;
+    /** Page description (rendered in <meta name="description"> tag) */
+    description?: string;
+    /** Open Graph image URL */
+    ogImage?: string;
+    /** Canonical URL */
+    canonical?: string;
+    /** JSON-LD structured data for rich snippets */
+    structuredData?: Record<string, any>;
+    /** Additional custom meta tags */
+    customMeta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+};
+/**
+ * Function that returns meta fields for the current page.
+ * Receives the data bridge context as a parameter, allowing access to
+ * data loaders, cart, user, location, and actions.
+ *
+ * @param data - The commerce components data interface with loaders and state
+ * @returns Meta fields for the current page (title, description, OG tags, etc.)
+ */
+export type StoreFrontMetaFieldsFunction = (data: CommerceComponentsDataInterface) => MetaFields | Promise<MetaFields>;
 export type RemoteModuleRegistry = {
     RouteablePages?: RoutablePageRegistryEntry[];
     StoreFrontHeader?: RemoteBoundaryComponent;
@@ -17,5 +48,13 @@ export type RemoteModuleRegistry = {
     StoreFrontHero?: RemoteBoundaryComponent;
     ProductDetailsMeta?: RemoteBoundaryComponent;
     ProductDetailsPrimary?: RemoteBoundaryComponent;
+    /**
+     * Function that provides meta fields for the current page.
+     * Replaces the StoreFrontMeta component approach.
+     *
+     * Called by the host app with the full data bridge context:
+     * `const metaFields = registry.getStoreFrontMetaFields?.(dataBridgeData)`
+     */
+    getStoreFrontMetaFields?: StoreFrontMetaFieldsFunction;
     events?: Events;
 };

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "MIT",
   "type": "module",
   "module": "./dist/esm/index.js",