@viu/emporix-sdk-react

@viu/emporix-sdk-react

React bindings for @viu/emporix-sdk, built on @tanstack/react-query v5. Supports React 18 & 19.

Install

pnpm add @viu/emporix-sdk-react @viu/emporix-sdk @tanstack/react-query react

@viu/emporix-sdk, @tanstack/react-query and react are peer dependencies.

Provider

import { EmporixClient } from "@viu/emporix-sdk";
import { EmporixProvider, createLocalStorage } from "@viu/emporix-sdk-react";

const client = new EmporixClient({
  tenant: "mytenant",
  credentials: { backend: { clientId: "", secret: "" }, storefront: { clientId: "x" } },
});

<EmporixProvider client={client} storage={createLocalStorage()}>
  <App />
</EmporixProvider>;

Create EmporixClient once (per app, or once per server for SSR) — never per request/render.

Hooks

Hook	Purpose
useCustomerSession()	customerToken, customer, isAuthenticated, login, signup, logout, refresh
useUpdateCustomer / useChangePassword / usePasswordReset	account management
useCustomerAddresses / useAddressMutations	address CRUD
useProduct / useProducts / useProductsInfinite / useProductByCode / useProductsByCodes / useProductSearch / useVariantChildren	product reads
useCategory / useCategories / useCategoriesInfinite / useCategoryTree / useProductsInCategory(Infinite) / useCategorySearch	category reads
useCart(cartId?) / useActiveCart(opts?) / useCreateCart()	cart read + bootstrap
useCartMutations(cartId?)	add/update/remove/clear/coupons/addresses — optimistic + rollback
useCheckout() / usePaymentModes()	checkout flow + payment-mode list
useMatchPrices() / useMatchPricesChunked()	price matching (chunked variant for large carts)
useProductMedia()	product media reads
useMyOrders / useMyOrdersInfinite / useOrder / useCancelOrder / useOrderTransition / useReorder	order history + actions
useSalesOrder / useUpdateSalesOrder	sales-order read + update
useAvailability / useAvailabilities	site-aware availability reads
useValidateCoupon / useRedeemCoupon	coupon validation + redemption
useMyRewardPoints / useMyRewardPointsSummary / useRedeemOptions / useRedeemRewardPoints	reward points
useMyReturns / useReturn / useCreateReturn	returns (RMA) self-service
useApprovals / useApproval / useCreateApproval / useUpdateApproval	B2B approval workflows
useShoppingLists / useCreateShoppingList / useDeleteShoppingList / useAddToShoppingList / useRemoveFromShoppingList / useSetShoppingListItemQuantity	shopping lists
useMySegments / useMySegmentItems / useMySegment{Products,Categories}(Infinite) / useMySegmentCategoryTree	customer-segment reads
useSites / useDefaultSite / useSiteContext	multi-site context
useActiveCompany / useCompanySwitcher	active legal entity (B2B)
useMyCompanies / useCompany / useCompanyContacts / useCompanyLocations / useCompanyGroups	B2B reads
useCreateCompany / useUpdateCompany / useDeleteCompany	B2B admin mutations
useAssignContact / useUpdateContactAssignment / useUnassignContact	B2B contact-assignment mutations
useCreateLocation / useUpdateLocation / useDeleteLocation	B2B location mutations

useProductSearch, useCategorySearch and useMyOrders({ q }) accept a raw q string or a type-safe mixin filter built with mixinQuery from @viu/emporix-mixins — see ../../docs/mixin-search.md.

Query keys are namespaced ["emporix", resource, ...args, meta] where meta holds the cache discriminators — at minimum { tenant, authKind }, plus siteCode for site-aware hooks and legalEntityId for B2B-aware hooks (cart, checkout, addresses, etc. invalidate automatically on company switch). Every query hook accepts { auth } to override the token kind for that call (default: customer if a token is stored, else anonymous).

Storage adapters

createMemoryStorage (default, SSR-safe), createLocalStorage, createSessionStorage (per-tab: survives reload, cleared on tab close), createCookieStorage. createLocalStorageStorage is a deprecated alias of createLocalStorage. Trade-offs and CSRF notes in ../../docs/react.md.

Errors & SSR

<EmporixErrorBoundary> and useEmporixErrorHandler for error coordination; prefetchProduct / prefetchCart for server-side hydration. See ../../docs/react.md.

Analytics & tracking

A typed, no-op-by-default telemetry channel (onTelemetry + useEmporixTelemetry) feeds any analytics sink. For Google Tag Manager / GA4 ecommerce — the dataLayer bridge, GA4 event mapping, a useTrackedCart wrapper, SSR + consent — see ../../docs/analytics.md.

Subpath exports

., ./provider, ./hooks, ./storage, ./ssr.

Authors

• Dominic Fritschi — Maintainer — VIU
• Andreas Nebiker — Contributor — VIU
• The Team at VIU — Contributors — VIU

License

This project is licensed under the MIT License — see the LICENSE file for details.