@nosto/nosto-react 2.11.0 → 2.12.0

package/dist/index.d.ts

@@ -437,7 +437,43 @@ export declare type ToCamelCase<T> = T extends (infer U)[] ? ToCamelCase<U>[] :
 } : T;
 
 /**
- * You can personalise your cart and checkout pages by using the `useNosto404` hook.
+ * You can personalise your 404 error pages by using the `useNosto404` hook.
+ *
+ * @example Basic 404 page usage
+ * ```tsx
+ * import { useNosto404 } from '@nosto/nosto-react'
+ *
+ * function NotFoundPage() {
+ *   useNosto404({
+ *     placements: ['notfound-nosto-1', 'notfound-popular-products']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Page Not Found</h1>
+ *       <p>Sorry, the page you're looking for doesn't exist.</p>
+ *       <div id="notfound-popular-products" />
+ *       <div id="notfound-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example 404 page with default placements
+ * ```tsx
+ * import { useNosto404 } from '@nosto/nosto-react'
+ *
+ * function Simple404Page() {
+ *   useNosto404() // Uses all available placements
+ *
+ *   return (
+ *     <div>
+ *       <h1>Oops! Page not found</h1>
+ *       <p>Let us help you find what you're looking for:</p>
+ *     </div>
+ *   )
+ * }
+ * ```
  *
  * @group Hooks
  */
@@ -446,6 +482,47 @@ export declare function useNosto404(props?: Nosto404Props): void;
 /**
  * You can personalise your category and collection pages by using the useNostoCategory hook.
  *
+ * @example Basic category page usage
+ * ```tsx
+ * import { useNostoCategory } from '@nosto/nosto-react'
+ *
+ * function CategoryPage({ categoryName }: { categoryName: string }) {
+ *   useNostoCategory({
+ *     category: categoryName,
+ *     placements: ['categorypage-nosto-1', 'categorypage-nosto-2']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Category: {categoryName}</h1>
+ *       <div id="categorypage-nosto-1" />
+ *       <div id="categorypage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Collection page with custom placements
+ * ```tsx
+ * import { useNostoCategory } from '@nosto/nosto-react'
+ *
+ * function CollectionPage({ collection }: { collection: { name: string, id: string } }) {
+ *   useNostoCategory({
+ *     category: `collection-${collection.id}`,
+ *     placements: ['collection-banner', 'collection-recommendations']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>{collection.name} Collection</h1>
+ *       <div id="collection-banner" />
+ *       {/\* Product grid here *\/}
+ *       <div id="collection-recommendations" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoCategory({ category, placements }: NostoCategoryProps): void;
@@ -453,6 +530,46 @@ export declare function useNostoCategory({ category, placements }: NostoCategory
 /**
  * You can personalise your cart and checkout pages by using the useNostoCheckout hook.
  *
+ * @example Basic cart page usage
+ * ```tsx
+ * import { useNostoCheckout } from '@nosto/nosto-react'
+ *
+ * function CartPage() {
+ *   useNostoCheckout({
+ *     placements: ['cartpage-nosto-1', 'cartpage-cross-sell']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Your Cart</h1>
+ *       {/\* Cart items here *\/}
+ *       <div id="cartpage-cross-sell" />
+ *       <div id="cartpage-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Checkout page with recommendations
+ * ```tsx
+ * import { useNostoCheckout } from '@nosto/nosto-react'
+ *
+ * function CheckoutPage() {
+ *   useNostoCheckout({
+ *     placements: ['checkout-upsell', 'checkout-last-chance']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Checkout</h1>
+ *       <div id="checkout-upsell" />
+ *       {/\* Checkout form here *\/}
+ *       <div id="checkout-last-chance" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoCheckout(props?: NostoCheckoutProps): void;
@@ -460,13 +577,88 @@ export declare function useNostoCheckout(props?: NostoCheckoutProps): void;
 /**
  * A hook that allows you to access the NostoContext and retrieve Nosto-related data from it in React components.
  *
- * @group Essential Functions
+ * @example
+ * ```tsx
+ * import { useNostoContext } from '@nosto/nosto-react'
+ *
+ * function NostoStatus() {
+ *   const { clientScriptLoaded, account, responseMode } = useNostoContext()
+ *
+ *   return (
+ *     <div>
+ *       <p>Account: {account}</p>
+ *       <p>Script loaded: {String(clientScriptLoaded)}</p>
+ *       <p>Response mode: {responseMode}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Using context for conditional rendering
+ * ```tsx
+ * import { useNostoContext } from '@nosto/nosto-react'
+ *
+ * function ConditionalRecommendations() {
+ *   const { clientScriptLoaded, recommendationComponent } = useNostoContext()
+ *
+ *   if (!clientScriptLoaded) {
+ *     return <div>Loading recommendations...</div>
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       {recommendationComponent && (
+ *         <div id="nosto-recommendation-placeholder" />
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @group Hooks
  */
 export declare function useNostoContext(): NostoContextType;
 
 /**
  * You can personalise your home page by using the useNostoHome hook.
  *
+ * @example Basic home page usage
+ * ```tsx
+ * import { useNostoHome } from '@nosto/nosto-react'
+ *
+ * function HomePage() {
+ *   useNostoHome({
+ *     placements: ['frontpage-nosto-1', 'frontpage-nosto-2', 'frontpage-hero']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <div id="frontpage-hero" />
+ *       <h1>Welcome to our store</h1>
+ *       <div id="frontpage-nosto-1" />
+ *       <div id="frontpage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Home page with default placements
+ * ```tsx
+ * import { useNostoHome } from '@nosto/nosto-react'
+ *
+ * function SimpleHomePage() {
+ *   // Uses all available placements configured in Nosto admin
+ *   useNostoHome()
+ *
+ *   return (
+ *     <div>
+ *       <h1>Home Page</h1>
+ *       {/\* Nosto will inject content into configured placements *\/}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoHome(props?: NostoHomeProps): void;
@@ -474,6 +666,57 @@ export declare function useNostoHome(props?: NostoHomeProps): void;
 /**
  * You can personalise your order-confirmation/thank-you page by using the `useNostoOrder` hook.
  *
+ * @example Basic order confirmation page usage
+ * ```tsx
+ * import { useNostoOrder } from '@nosto/nosto-react'
+ *
+ * function OrderConfirmationPage({ order }: { order: Order }) {
+ *   useNostoOrder({
+ *     order: order,
+ *     placements: ['orderconfirm-nosto-1', 'orderconfirm-cross-sell']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Order Confirmed!</h1>
+ *       <p>Order #{order.order_number}</p>
+ *       <div id="orderconfirm-cross-sell" />
+ *       <div id="orderconfirm-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Complete order with camelCase conversion
+ * ```tsx
+ * import { useNostoOrder } from '@nosto/nosto-react'
+ *
+ * function ThankYouPage({ orderData }: { orderData: ToCamelCase<Order> }) {
+ *   useNostoOrder({
+ *     order: {
+ *       orderNumber: orderData.orderNumber,
+ *       customerEmail: orderData.customerEmail,
+ *       purchasedItems: orderData.purchasedItems.map(item => ({
+ *         productId: item.productId,
+ *         skuId: item.skuId,
+ *         name: item.name,
+ *         unitPrice: item.unitPrice,
+ *         quantity: item.quantity
+ *       }))
+ *     },
+ *     placements: ['thankyou-recommendations', 'thankyou-reviews']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Thank you for your purchase!</h1>
+ *       <div id="thankyou-recommendations" />
+ *       <div id="thankyou-reviews" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoOrder({ order, placements }: NostoOrderProps): void;
@@ -481,6 +724,64 @@ export declare function useNostoOrder({ order, placements }: NostoOrderProps): v
 /**
  * You can personalise your miscellaneous pages by using the useNostoOther hook.
  *
+ * @example Basic usage for contact page
+ * ```tsx
+ * import { useNostoOther } from '@nosto/nosto-react'
+ *
+ * function ContactPage() {
+ *   useNostoOther({
+ *     placements: ['contactpage-nosto-1', 'contactpage-popular-products']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Contact Us</h1>
+ *       <form>
+ *         {/\* Contact form fields *\/}
+ *       </form>
+ *       <div id="contactpage-popular-products" />
+ *       <div id="contactpage-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example About page with recommendations
+ * ```tsx
+ * import { useNostoOther } from '@nosto/nosto-react'
+ *
+ * function AboutPage() {
+ *   useNostoOther({
+ *     placements: ['aboutpage-featured', 'aboutpage-bestsellers']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>About Our Company</h1>
+ *       <p>Learn more about our story...</p>
+ *       <div id="aboutpage-featured" />
+ *       <div id="aboutpage-bestsellers" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Default placements for any other page
+ * ```tsx
+ * import { useNostoOther } from '@nosto/nosto-react'
+ *
+ * function GenericPage() {
+ *   useNostoOther() // Uses all available placements
+ *
+ *   return (
+ *     <div>
+ *       <h1>Generic Page</h1>
+ *       <p>This could be any page type not covered by other hooks.</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoOther(props?: NostoOtherProps): void;
@@ -488,6 +789,58 @@ export declare function useNostoOther(props?: NostoOtherProps): void;
 /**
  * You can personalise your product pages by using the useNostoProduct hook.
  *
+ * @example Basic product page usage
+ * ```tsx
+ * import { useNostoProduct } from '@nosto/nosto-react'
+ *
+ * function ProductPage({ productId }: { productId: string }) {
+ *   useNostoProduct({
+ *     product: productId,
+ *     placements: ['productpage-nosto-1', 'productpage-nosto-2']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Product Details</h1>
+ *       <div id="productpage-nosto-1" />
+ *       <div id="productpage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Advanced product page with full tagging
+ * ```tsx
+ * import { useNostoProduct } from '@nosto/nosto-react'
+ *
+ * function AdvancedProductPage({ product }: { product: Product }) {
+ *   useNostoProduct({
+ *     product: product.id,
+ *     reference: `product-${product.id}`,
+ *     tagging: {
+ *       product_id: product.id,
+ *       name: product.name,
+ *       url: product.url,
+ *       price: product.price,
+ *       list_price: product.listPrice,
+ *       image_url: product.imageUrl,
+ *       categories: product.categories,
+ *       brand: product.brand,
+ *       selected_sku_id: product.selectedVariant?.id
+ *     },
+ *     placements: ['productpage-cross-sell', 'productpage-upsell']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>{product.name}</h1>
+ *       <div id="productpage-cross-sell" />
+ *       <div id="productpage-upsell" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoProduct({ product, tagging, placements, reference }: NostoProductProps): void;
@@ -495,6 +848,55 @@ export declare function useNostoProduct({ product, tagging, placements, referenc
 /**
  * You can personalise your search pages by using the useNostoSearch hook.
  *
+ * @example Basic search page usage
+ * ```tsx
+ * import { useNostoSearch } from '@nosto/nosto-react'
+ *
+ * function SearchPage({ searchQuery }: { searchQuery: string }) {
+ *   useNostoSearch({
+ *     query: searchQuery,
+ *     placements: ['searchpage-nosto-1', 'searchpage-no-results']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Search Results for "{searchQuery}"</h1>
+ *       {/\* Search results here *\/}
+ *       <div id="searchpage-nosto-1" />
+ *       <div id="searchpage-no-results" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Search with dynamic query updates
+ * ```tsx
+ * import { useNostoSearch } from '@nosto/nosto-react'
+ * import { useState } from 'react'
+ *
+ * function SearchPageWithFilters() {
+ *   const [query, setQuery] = useState('')
+ *
+ *   useNostoSearch({
+ *     query: query,
+ *     placements: ['search-recommendations', 'search-trending']
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="text"
+ *         value={query}
+ *         onChange={(e) => setQuery(e.target.value)}
+ *         placeholder="Search products..."
+ *       />
+ *       <div id="search-recommendations" />
+ *       <div id="search-trending" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoSearch({ query, placements }: NostoSearchProps): void;
@@ -502,6 +904,62 @@ export declare function useNostoSearch({ query, placements }: NostoSearchProps):
 /**
  * Nosto React requires that you pass it the details of current cart contents and the details of the currently logged-in customer, if any, on every route change.
  *
+ * @example Basic session management
+ * ```tsx
+ * import { useNostoSession } from '@nosto/nosto-react'
+ *
+ * function App({ cart, user }: { cart?: Cart, user?: Customer }) {
+ *   useNostoSession({
+ *     cart: cart ? {
+ *       items: cart.items.map(item => ({
+ *         product_id: item.productId,
+ *         sku_id: item.skuId,
+ *         name: item.name,
+ *         unit_price: item.price,
+ *         quantity: item.quantity
+ *       }))
+ *     } : undefined,
+ *     customer: user ? {
+ *       customer_reference: user.id,
+ *       email: user.email,
+ *       first_name: user.firstName,
+ *       last_name: user.lastName
+ *     } : undefined
+ *   })
+ *
+ *   return <div>App content</div>
+ * }
+ * ```
+ *
+ * @example Route-based session updates
+ * ```tsx
+ * import { useNostoSession } from '@nosto/nosto-react'
+ * import { useEffect, useState } from 'react'
+ *
+ * function SessionProvider({ children }: { children: React.ReactNode }) {
+ *   const [cart, setCart] = useState<Cart | null>(null)
+ *   const [customer, setCustomer] = useState<Customer | null>(null)
+ *
+ *   useEffect(() => {
+ *     // Load cart and customer data
+ *     loadCartData().then(setCart)
+ *     loadCustomerData().then(setCustomer)
+ *   }, [])
+ *
+ *   useNostoSession({
+ *     cart: cart ? {
+ *       items: cart.items
+ *     } : undefined,
+ *     customer: customer ? {
+ *       customerReference: customer.id,
+ *       email: customer.email
+ *     } : undefined
+ *   })
+ *
+ *   return <>{children}</>
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export declare function useNostoSession({ cart, customer }?: NostoSessionProps): void;

package/dist/index.es.js

@@ -97,7 +97,6 @@ function d(e, t, n) {
 }
 function F(e) {
   return x(e.recommendationComponent, {
-    // eslint-disable-next-line react/prop-types
     nostoRecommendation: e.nostoRecommendation
   });
 }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@nosto/nosto-react",
   "description": "Component library to simply implementing Nosto on React.",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "author": "Mridang Agarwalla, Dominik Gilg",
   "license": "ISC",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Nosto/nosto-react.git"
@@ -48,8 +49,8 @@
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.0",
     "@types/user-event": "^4.1.1",
-    "@vitejs/plugin-react": "^5.0.0",
-    "@vitest/coverage-v8": "^3.0.9",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/coverage-v8": "^4.0.10",
     "eslint": "^9.13.0",
     "eslint-plugin-barrel-files": "^3.0.1",
     "eslint-plugin-promise": "^7.1.0",
@@ -66,18 +67,18 @@
     "typedoc": "^0.28.9",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.39.0",
-    "vite": "^7.0.2",
+    "vite": "^7.2.2",
     "vite-plugin-dts": "^4.2.2",
-    "vitest": "^3.0.2"
+    "vitest": "^4.0.10"
   },
   "main": "./dist/index.umd.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.es.js",
-      "require": "./dist/index.umd.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.umd.js"
     }
   },
   "bugs": {

package/src/hooks/useDeepCompareEffect.ts

@@ -1,6 +1,47 @@
 import { useEffect, useRef, useMemo, type EffectCallback, type DependencyList } from "react"
 import { deepCompare } from "../utils/compare"
 
+/**
+ * Similar to useEffect but performs deep comparison of dependencies instead of shallow comparison.
+ * Useful when dependencies are objects or arrays that may be recreated on each render.
+ * 
+ * @example
+ * ```tsx
+ * import { useDeepCompareEffect } from '@nosto/nosto-react'
+ * 
+ * function MyComponent({ user }: { user: { id: string, preferences: string[] } }) {
+ *   useDeepCompareEffect(() => {
+ *     console.log('User preferences changed:', user.preferences)
+ *     // This will only run when user object actually changes,
+ *     // not when it's recreated with same values
+ *   }, [user])
+ * 
+ *   return <div>User: {user.id}</div>
+ * }
+ * ```
+ * 
+ * @example Comparing arrays and objects
+ * ```tsx
+ * import { useDeepCompareEffect } from '@nosto/nosto-react'
+ * 
+ * function ProductList({ filters, sortOptions }: { 
+ *   filters: { category: string, price: { min: number, max: number } }
+ *   sortOptions: string[]
+ * }) {
+ *   useDeepCompareEffect(() => {
+ *     // This effect will only run when filters or sortOptions actually change
+ *     fetchProducts(filters, sortOptions)
+ *   }, [filters, sortOptions])
+ * 
+ *   return <div>Product list</div>
+ * }
+ * ```
+ * 
+ * @param callback The effect callback function
+ * @param dependencies Array of dependencies to deep compare
+ * 
+ * @group Hooks
+ */
 export function useDeepCompareEffect(callback: EffectCallback, dependencies: DependencyList) {
   return useEffect(callback, useDeepCompareMemoize(dependencies))
 }

package/src/hooks/useLoadClientScript.ts

@@ -7,6 +7,59 @@ type NostoScriptProps = Pick<NostoProviderProps, "account" | "host" | "shopifyMa
 
 const defaultAttributes = { "nosto-client-script": "" }
 
+/**
+ * Hook for loading the Nosto client script and managing its load state.
+ * 
+ * @example
+ * ```tsx
+ * import { useLoadClientScript } from '@nosto/nosto-react'
+ * 
+ * function MyNostoProvider() {
+ *   const { clientScriptLoaded } = useLoadClientScript({
+ *     account: 'shopify-123456',
+ *     loadScript: true,
+ *     shopifyMarkets: {
+ *       marketId: 'US',
+ *       language: 'en'
+ *     }
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       {clientScriptLoaded ? (
+ *         <p>Nosto script loaded successfully</p>
+ *       ) : (
+ *         <p>Loading Nosto script...</p>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Custom script loader
+ * ```tsx
+ * import { useLoadClientScript } from '@nosto/nosto-react'
+ * 
+ * function CustomNostoProvider() {
+ *   const customScriptLoader = (url: string) => {
+ *     const script = document.createElement('script')
+ *     script.src = url
+ *     script.async = true
+ *     document.head.appendChild(script)
+ *     return script
+ *   }
+ * 
+ *   const { clientScriptLoaded } = useLoadClientScript({
+ *     account: 'my-nosto-account',
+ *     scriptLoader: customScriptLoader
+ *   })
+ * 
+ *   return <div>Script loaded: {String(clientScriptLoaded)}</div>
+ * }
+ * ```
+ * 
+ * @group Hooks
+ */
 export function useLoadClientScript(props: NostoScriptProps) {
   const {
     scriptLoader = scriptLoaderFn,

package/src/hooks/useNosto404.tsx

@@ -7,7 +7,43 @@ import { useRenderCampaigns } from "./useRenderCampaigns"
 export type Nosto404Props = { placements?: string[] }
 
 /**
- * You can personalise your cart and checkout pages by using the `useNosto404` hook.
+ * You can personalise your 404 error pages by using the `useNosto404` hook.
+ *
+ * @example Basic 404 page usage
+ * ```tsx
+ * import { useNosto404 } from '@nosto/nosto-react'
+ * 
+ * function NotFoundPage() {
+ *   useNosto404({
+ *     placements: ['notfound-nosto-1', 'notfound-popular-products']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Page Not Found</h1>
+ *       <p>Sorry, the page you're looking for doesn't exist.</p>
+ *       <div id="notfound-popular-products" />
+ *       <div id="notfound-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example 404 page with default placements
+ * ```tsx
+ * import { useNosto404 } from '@nosto/nosto-react'
+ * 
+ * function Simple404Page() {
+ *   useNosto404() // Uses all available placements
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Oops! Page not found</h1>
+ *       <p>Let us help you find what you're looking for:</p>
+ *     </div>
+ *   )
+ * }
+ * ```
  *
  * @group Hooks
  */

package/src/hooks/useNostoApi.ts

@@ -4,6 +4,51 @@ import { useDeepCompareEffect } from "./useDeepCompareEffect"
 import { nostojs } from "@nosto/nosto-js"
 import { API } from "@nosto/nosto-js/client"
 
+/**
+ * Hook for executing code that requires access to the Nosto API.
+ * Waits for the client script to load before executing the callback.
+ * 
+ * @example
+ * ```tsx
+ * import { useNostoApi } from '@nosto/nosto-react'
+ * 
+ * function ProductRecommendations({ productId }: { productId: string }) {
+ *   useNostoApi(async (api) => {
+ *     const data = await api
+ *       .defaultSession()
+ *       .viewProduct(productId)
+ *       .setPlacements(['productpage-nosto-1', 'productpage-nosto-2'])
+ *       .load()
+ *     
+ *     console.log('Recommendations loaded:', data)
+ *   }, [productId])
+ * 
+ *   return <div>Product recommendations will appear here</div>
+ * }
+ * ```
+ * 
+ * @example Using deep comparison for complex dependencies
+ * ```tsx
+ * import { useNostoApi } from '@nosto/nosto-react'
+ * 
+ * function OrderThankYou({ order }: { order: Order }) {
+ *   useNostoApi(async (api) => {
+ *     await api
+ *       .defaultSession()
+ *       .addOrder(order)
+ *       .load()
+ *   }, [order], { deep: true })
+ * 
+ *   return <div>Thank you for your order!</div>
+ * }
+ * ```
+ * 
+ * @param cb Callback function that receives the Nosto API instance
+ * @param deps Optional dependency list for useEffect
+ * @param flags Optional flags, including `deep` for deep comparison of dependencies
+ * 
+ * @group Hooks
+ */
 export function useNostoApi(cb: (api: API) => void, deps?: DependencyList, flags?: { deep?: boolean }): void {
   const { clientScriptLoaded } = useNostoContext()
   const useEffectFn = flags?.deep ? useDeepCompareEffect : useEffect

package/src/hooks/useNostoCategory.tsx

@@ -12,6 +12,47 @@ export type NostoCategoryProps = {
 /**
  * You can personalise your category and collection pages by using the useNostoCategory hook.
  *
+ * @example Basic category page usage
+ * ```tsx
+ * import { useNostoCategory } from '@nosto/nosto-react'
+ * 
+ * function CategoryPage({ categoryName }: { categoryName: string }) {
+ *   useNostoCategory({
+ *     category: categoryName,
+ *     placements: ['categorypage-nosto-1', 'categorypage-nosto-2']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Category: {categoryName}</h1>
+ *       <div id="categorypage-nosto-1" />
+ *       <div id="categorypage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Collection page with custom placements
+ * ```tsx
+ * import { useNostoCategory } from '@nosto/nosto-react'
+ * 
+ * function CollectionPage({ collection }: { collection: { name: string, id: string } }) {
+ *   useNostoCategory({
+ *     category: `collection-${collection.id}`,
+ *     placements: ['collection-banner', 'collection-recommendations']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>{collection.name} Collection</h1>
+ *       <div id="collection-banner" />
+ *       {/\* Product grid here *\/}
+ *       <div id="collection-recommendations" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoCategory({ category, placements }: NostoCategoryProps) {

package/src/hooks/useNostoCheckout.tsx

@@ -9,6 +9,46 @@ export type NostoCheckoutProps = { placements?: string[] }
 /**
  * You can personalise your cart and checkout pages by using the useNostoCheckout hook.
  *
+ * @example Basic cart page usage
+ * ```tsx
+ * import { useNostoCheckout } from '@nosto/nosto-react'
+ * 
+ * function CartPage() {
+ *   useNostoCheckout({
+ *     placements: ['cartpage-nosto-1', 'cartpage-cross-sell']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Your Cart</h1>
+ *       {/\* Cart items here *\/}
+ *       <div id="cartpage-cross-sell" />
+ *       <div id="cartpage-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Checkout page with recommendations
+ * ```tsx
+ * import { useNostoCheckout } from '@nosto/nosto-react'
+ * 
+ * function CheckoutPage() {
+ *   useNostoCheckout({
+ *     placements: ['checkout-upsell', 'checkout-last-chance']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Checkout</h1>
+ *       <div id="checkout-upsell" />
+ *       {/\* Checkout form here *\/}
+ *       <div id="checkout-last-chance" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoCheckout(props?: NostoCheckoutProps) {

package/src/hooks/useNostoContext.ts

@@ -4,7 +4,45 @@ import { NostoContext, NostoContextType } from "../context"
 /**
  * A hook that allows you to access the NostoContext and retrieve Nosto-related data from it in React components.
  *
- * @group Essential Functions
+ * @example
+ * ```tsx
+ * import { useNostoContext } from '@nosto/nosto-react'
+ * 
+ * function NostoStatus() {
+ *   const { clientScriptLoaded, account, responseMode } = useNostoContext()
+ * 
+ *   return (
+ *     <div>
+ *       <p>Account: {account}</p>
+ *       <p>Script loaded: {String(clientScriptLoaded)}</p>
+ *       <p>Response mode: {responseMode}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Using context for conditional rendering
+ * ```tsx
+ * import { useNostoContext } from '@nosto/nosto-react'
+ * 
+ * function ConditionalRecommendations() {
+ *   const { clientScriptLoaded, recommendationComponent } = useNostoContext()
+ * 
+ *   if (!clientScriptLoaded) {
+ *     return <div>Loading recommendations...</div>
+ *   }
+ * 
+ *   return (
+ *     <div>
+ *       {recommendationComponent && (
+ *         <div id="nosto-recommendation-placeholder" />
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @group Hooks
  */
 export function useNostoContext(): NostoContextType {
   return useContext(NostoContext)

package/src/hooks/useNostoHome.tsx

@@ -9,6 +9,43 @@ export type NostoHomeProps = { placements?: string[] }
 /**
  * You can personalise your home page by using the useNostoHome hook.
  *
+ * @example Basic home page usage
+ * ```tsx
+ * import { useNostoHome } from '@nosto/nosto-react'
+ * 
+ * function HomePage() {
+ *   useNostoHome({
+ *     placements: ['frontpage-nosto-1', 'frontpage-nosto-2', 'frontpage-hero']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <div id="frontpage-hero" />
+ *       <h1>Welcome to our store</h1>
+ *       <div id="frontpage-nosto-1" />
+ *       <div id="frontpage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Home page with default placements
+ * ```tsx
+ * import { useNostoHome } from '@nosto/nosto-react'
+ * 
+ * function SimpleHomePage() {
+ *   // Uses all available placements configured in Nosto admin
+ *   useNostoHome()
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Home Page</h1>
+ *       {/\* Nosto will inject content into configured placements *\/}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoHome(props?: NostoHomeProps) {

package/src/hooks/useNostoOrder.tsx

@@ -15,6 +15,57 @@ export type NostoOrderProps = {
 /**
  * You can personalise your order-confirmation/thank-you page by using the `useNostoOrder` hook.
  *
+ * @example Basic order confirmation page usage
+ * ```tsx
+ * import { useNostoOrder } from '@nosto/nosto-react'
+ * 
+ * function OrderConfirmationPage({ order }: { order: Order }) {
+ *   useNostoOrder({
+ *     order: order,
+ *     placements: ['orderconfirm-nosto-1', 'orderconfirm-cross-sell']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Order Confirmed!</h1>
+ *       <p>Order #{order.order_number}</p>
+ *       <div id="orderconfirm-cross-sell" />
+ *       <div id="orderconfirm-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Complete order with camelCase conversion
+ * ```tsx
+ * import { useNostoOrder } from '@nosto/nosto-react'
+ * 
+ * function ThankYouPage({ orderData }: { orderData: ToCamelCase<Order> }) {
+ *   useNostoOrder({
+ *     order: {
+ *       orderNumber: orderData.orderNumber,
+ *       customerEmail: orderData.customerEmail,
+ *       purchasedItems: orderData.purchasedItems.map(item => ({
+ *         productId: item.productId,
+ *         skuId: item.skuId,
+ *         name: item.name,
+ *         unitPrice: item.unitPrice,
+ *         quantity: item.quantity
+ *       }))
+ *     },
+ *     placements: ['thankyou-recommendations', 'thankyou-reviews']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Thank you for your purchase!</h1>
+ *       <div id="thankyou-recommendations" />
+ *       <div id="thankyou-reviews" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoOrder({ order, placements }: NostoOrderProps) {

package/src/hooks/useNostoOther.tsx

@@ -9,6 +9,64 @@ export type NostoOtherProps = { placements?: string[] }
 /**
  * You can personalise your miscellaneous pages by using the useNostoOther hook.
  *
+ * @example Basic usage for contact page
+ * ```tsx
+ * import { useNostoOther } from '@nosto/nosto-react'
+ * 
+ * function ContactPage() {
+ *   useNostoOther({
+ *     placements: ['contactpage-nosto-1', 'contactpage-popular-products']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Contact Us</h1>
+ *       <form>
+ *         {/\* Contact form fields *\/}
+ *       </form>
+ *       <div id="contactpage-popular-products" />
+ *       <div id="contactpage-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example About page with recommendations
+ * ```tsx
+ * import { useNostoOther } from '@nosto/nosto-react'
+ * 
+ * function AboutPage() {
+ *   useNostoOther({
+ *     placements: ['aboutpage-featured', 'aboutpage-bestsellers']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>About Our Company</h1>
+ *       <p>Learn more about our story...</p>
+ *       <div id="aboutpage-featured" />
+ *       <div id="aboutpage-bestsellers" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Default placements for any other page
+ * ```tsx
+ * import { useNostoOther } from '@nosto/nosto-react'
+ * 
+ * function GenericPage() {
+ *   useNostoOther() // Uses all available placements
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Generic Page</h1>
+ *       <p>This could be any page type not covered by other hooks.</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoOther(props?: NostoOtherProps) {

package/src/hooks/useNostoProduct.tsx

@@ -15,6 +15,58 @@ export type NostoProductProps = {
 /**
  * You can personalise your product pages by using the useNostoProduct hook.
  *
+ * @example Basic product page usage
+ * ```tsx
+ * import { useNostoProduct } from '@nosto/nosto-react'
+ * 
+ * function ProductPage({ productId }: { productId: string }) {
+ *   useNostoProduct({
+ *     product: productId,
+ *     placements: ['productpage-nosto-1', 'productpage-nosto-2']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Product Details</h1>
+ *       <div id="productpage-nosto-1" />
+ *       <div id="productpage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Advanced product page with full tagging
+ * ```tsx
+ * import { useNostoProduct } from '@nosto/nosto-react'
+ * 
+ * function AdvancedProductPage({ product }: { product: Product }) {
+ *   useNostoProduct({
+ *     product: product.id,
+ *     reference: `product-${product.id}`,
+ *     tagging: {
+ *       product_id: product.id,
+ *       name: product.name,
+ *       url: product.url,
+ *       price: product.price,
+ *       list_price: product.listPrice,
+ *       image_url: product.imageUrl,
+ *       categories: product.categories,
+ *       brand: product.brand,
+ *       selected_sku_id: product.selectedVariant?.id
+ *     },
+ *     placements: ['productpage-cross-sell', 'productpage-upsell']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>{product.name}</h1>
+ *       <div id="productpage-cross-sell" />
+ *       <div id="productpage-upsell" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoProduct({ product, tagging, placements, reference }: NostoProductProps) {

package/src/hooks/useNostoSearch.tsx

@@ -12,6 +12,55 @@ export type NostoSearchProps = {
 /**
  * You can personalise your search pages by using the useNostoSearch hook.
  *
+ * @example Basic search page usage
+ * ```tsx
+ * import { useNostoSearch } from '@nosto/nosto-react'
+ * 
+ * function SearchPage({ searchQuery }: { searchQuery: string }) {
+ *   useNostoSearch({
+ *     query: searchQuery,
+ *     placements: ['searchpage-nosto-1', 'searchpage-no-results']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Search Results for "{searchQuery}"</h1>
+ *       {/\* Search results here *\/}
+ *       <div id="searchpage-nosto-1" />
+ *       <div id="searchpage-no-results" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Search with dynamic query updates
+ * ```tsx
+ * import { useNostoSearch } from '@nosto/nosto-react'
+ * import { useState } from 'react'
+ * 
+ * function SearchPageWithFilters() {
+ *   const [query, setQuery] = useState('')
+ * 
+ *   useNostoSearch({
+ *     query: query,
+ *     placements: ['search-recommendations', 'search-trending']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <input 
+ *         type="text" 
+ *         value={query}
+ *         onChange={(e) => setQuery(e.target.value)}
+ *         placeholder="Search products..."
+ *       />
+ *       <div id="search-recommendations" />
+ *       <div id="search-trending" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoSearch({ query, placements }: NostoSearchProps) {

package/src/hooks/useNostoSession.tsx

@@ -16,6 +16,62 @@ export type NostoSessionProps = {
 /**
  * Nosto React requires that you pass it the details of current cart contents and the details of the currently logged-in customer, if any, on every route change.
  *
+ * @example Basic session management
+ * ```tsx
+ * import { useNostoSession } from '@nosto/nosto-react'
+ * 
+ * function App({ cart, user }: { cart?: Cart, user?: Customer }) {
+ *   useNostoSession({
+ *     cart: cart ? {
+ *       items: cart.items.map(item => ({
+ *         product_id: item.productId,
+ *         sku_id: item.skuId,
+ *         name: item.name,
+ *         unit_price: item.price,
+ *         quantity: item.quantity
+ *       }))
+ *     } : undefined,
+ *     customer: user ? {
+ *       customer_reference: user.id,
+ *       email: user.email,
+ *       first_name: user.firstName,
+ *       last_name: user.lastName
+ *     } : undefined
+ *   })
+ * 
+ *   return <div>App content</div>
+ * }
+ * ```
+ * 
+ * @example Route-based session updates
+ * ```tsx
+ * import { useNostoSession } from '@nosto/nosto-react'
+ * import { useEffect, useState } from 'react'
+ * 
+ * function SessionProvider({ children }: { children: React.ReactNode }) {
+ *   const [cart, setCart] = useState<Cart | null>(null)
+ *   const [customer, setCustomer] = useState<Customer | null>(null)
+ * 
+ *   useEffect(() => {
+ *     // Load cart and customer data
+ *     loadCartData().then(setCart)
+ *     loadCustomerData().then(setCustomer)
+ *   }, [])
+ * 
+ *   useNostoSession({
+ *     cart: cart ? {
+ *       items: cart.items
+ *     } : undefined,
+ *     customer: customer ? {
+ *       customerReference: customer.id,
+ *       email: customer.email
+ *     } : undefined
+ *   })
+ * 
+ *   return <>{children}</>
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoSession({ cart, customer }: NostoSessionProps = {}) {

package/src/hooks/useRenderCampaigns.tsx

@@ -14,7 +14,6 @@ function RecommendationComponentWrapper(props: {
   nostoRecommendation: Recommendation
 }) {
   return cloneElement(props.recommendationComponent, {
-    // eslint-disable-next-line react/prop-types
     nostoRecommendation: props.nostoRecommendation
   })
 }
@@ -31,6 +30,66 @@ function injectCampaigns(data: CampaignData) {
   injectPlacements(data.recommendations)
 }
 
+/**
+ * Hook for rendering Nosto campaigns and recommendations. Handles both HTML and client-side rendering modes.
+ * This hook is typically used internally by other Nosto hooks but can be used directly for custom implementations.
+ * 
+ * @example Basic usage with HTML mode
+ * ```tsx
+ * import { useRenderCampaigns } from '@nosto/nosto-react'
+ * 
+ * function CustomRecommendations() {
+ *   const { renderCampaigns } = useRenderCampaigns()
+ * 
+ *   useEffect(() => {
+ *     // When using HTML response mode, campaigns are injected as HTML
+ *     const campaignData = {
+ *       campaigns: {
+ *         content: {
+ *           'my-placement-id': '<div>Nosto content</div>'
+ *         }
+ *       },
+ *       recommendations: {}
+ *     }
+ *     renderCampaigns(campaignData)
+ *   }, [renderCampaigns])
+ * 
+ *   return <div id="my-placement-id" />
+ * }
+ * ```
+ * 
+ * @example Client-side rendering with React components
+ * ```tsx
+ * import { useRenderCampaigns } from '@nosto/nosto-react'
+ * 
+ * function ClientSideRecommendations() {
+ *   const { renderCampaigns } = useRenderCampaigns()
+ * 
+ *   useEffect(() => {
+ *     // When using client-side rendering, recommendations are rendered as React components
+ *     const campaignData = {
+ *       campaigns: {
+ *         recommendations: {
+ *           'my-placement-id': {
+ *             result_id: 'abc123',
+ *             products: [
+ *               { product_id: '1', name: 'Product 1', url: '/product/1' },
+ *               { product_id: '2', name: 'Product 2', url: '/product/2' }
+ *             ]
+ *           }
+ *         }
+ *       },
+ *       recommendations: {}
+ *     }
+ *     renderCampaigns(campaignData)
+ *   }, [renderCampaigns])
+ * 
+ *   return <div id="my-placement-id" />
+ * }
+ * ```
+ * 
+ * @group Hooks
+ */
 export function useRenderCampaigns() {
   const { responseMode, recommendationComponent } = useNostoContext()
   const placementRefs = useRef<Record<string, Root>>({})