Do's and Don'ts

This guide provides a quick reference for the best practices when composing Archibald commerce modules together. Following these patterns ensures high performance, security, and maintainability.

Module Boundaries

Product vs. Search

Scenario	✅ Do	❌ Don't
Product Detail Page	Use useProduct(code) to fetch full details.	Use useSearch to find a single product.
Product Listing Page	Use useSearch or useSearchCategory.	Loop over useProduct calls for a list.
Related Products	Use useSearchProductRecommendations.	Hardcode a list of codes and use useProducts.
"Instant" Search Dropdown	Use useSearchProductSuggestions.	Use a full useSearch query as the user types.

• Why?: useSearch is optimized for filtering, facets, and pagination. useProduct is intended for fetching the complete data tree of a specific item.

State and Composition

Cart and UI Updates

• ✅ Do: Use useCartClient().subscribe('cart', ...) to react to changes from any part of the app.
• ❌ Don't: Manually refetch the cart in a component after calling addToCart.
• Why?: The CartClient is a single source of truth. Subscribing to its events ensures your UI (like a header badge) stays in sync regardless of where the mutation was triggered.

Personalization and CMS

• ✅ Do: Use useFeatureFlagActive to decide which CMS path or slot to render.
• ❌ Don't: Fetch all CMS content and then hide parts of it with CSS based on flags.
• Why?: Toggling at the hook level prevents unnecessary network requests and keeps the DOM lean.

Performance and SSR

Hydration and Loading

• ✅ Do: Call await preloadAll() in your server's initServer method.
• ❌ Don't: Forget the fallback skeleton in Loadable components.
• Why?: Without server preloading, your code-split components will "pop in" after the page loads, hurting your Core Web Vitals and SEO.

Caching Strategy

• ✅ Do: Set long ttl values for static data (Categories) and short ttl for volatile data (Stock).
• ❌ Don't: Use the same default cache settings for every useFetch call.
• Why?: Intelligent caching reduces backend load and improves the user-perceived speed of the application.

Security

Data Integrity

• ✅ Do: Always re-validate price and cart totals on the server before checkout.
• ❌ Don't: Pass price or discount values from the client to the server during mutations.
• Why?: Client-side data can be tampered with. The server should always fetch the latest "source of truth" from the SAP Commerce provider.