Implement the Catalog module

A Catalog replacement module reads everything it needs from the Catalog module context, rather than calling the InStore backend.

Read Catalog state and operations

The provider adds the location and workstation to every search, so your module does not pass them.

The context holds no loading or error state. Track both in your own module.

Fetch and read

Handle failures

The operations differ in what they leave behind:

• getCategories rejects and resets categoryList to an empty list.
• getCategoryProducts rejects and leaves the cache as it was, so a retry is safe.
• searchProducts rejects and writes nothing, so a failed search is not an empty search. Distinguish the two in your module, because only a failure is worth a retry.
• addProductToCart rejects with a message that names the cause.
• checkCatalogParameter and checkUserPermission never throw. They return false for anything they can't confirm.

Check permissions and parameters

Both checks also accept a permission or parameter name that its enum doesn't list, passed as a string.

Gate the controls that add a Product on both checks. A missing permission and an inactive parameter each prevent the action, so treat either result as a reason to hide or deactivate the control. Your customers don't see the difference at checkout.

Render a minimal Catalog

Expose a root component that defines your routes:

import React from 'react';
import { Route, Routes } from 'react-router-dom';

import { CatalogPage } from './components/CatalogPage';

const App = () => (
  <Routes>
    <Route index element={<CatalogPage />} />
  </Routes>
);

export default App;

Then read the context, search, and render the results:

import {
  CatalogModuleParameter,
  CatalogModuleUserPermission,
  toProductView,
  useCatalogModuleContext,
} from 'instoreState/context/CatalogModuleContext';
import { useLocalizationContext } from 'instoreState/locale';
import React, { useCallback, useState } from 'react';

export const CatalogPage = () => {
  const { locale, t } = useLocalizationContext();
  const {
    searchResults,
    searchProducts,
    addProductToCart,
    checkCatalogParameter,
    checkUserPermission,
  } = useCatalogModuleContext();
  const [term, setTerm] = useState('');
  const [busy, setBusy] = useState(false);
  const [message, setMessage] = useState('');

  const canSell =
    checkUserPermission(CatalogModuleUserPermission.SELL_ITEM) &&
    checkCatalogParameter(CatalogModuleParameter.ALLOW_SELL_ITEM);

  const search = useCallback(async () => {
    setBusy(true);
    setMessage('');

    try {
      await searchProducts({
        query: { fullText: { field: 'name', language: locale, value: term } },
        limit: 24,
        offset: 0,
      });
    } catch (error) {
      setMessage(t('Catalog.search_failed'));
    } finally {
      setBusy(false);
    }
  }, [locale, searchProducts, t, term]);

  const add = useCallback(
    async (productId: string) => {
      try {
        await addProductToCart({ productId, quantity: 1 });
      } catch (error) {
        setMessage(t('Catalog.product_detail.labels.error_add'));
      }
    },
    [addProductToCart, t],
  );

  return (
    <div>
      <input
        aria-label={t('Common.search')}
        value={term}
        onChange={(event) => setTerm(event.target.value)}
      />
      <button onClick={search}>{t('Common.search')}</button>
      {busy ? <p role="status">Searching</p> : null}
      {message ? <p role="alert">{message}</p> : null}
      {searchResults.map((product) => {
        const view = toProductView(product, locale);

        if (!view) {
          return null;
        }

        return (
          <article key={view.id}>
            <span>{view.name}</span>
            <span>{view.priceDinero.toFormat()}</span>
            {canSell ? (
              <button onClick={() => add(view.id)}>
                {t('Catalog.add_to_sale')}
              </button>
            ) : null}
          </article>
        );
      })}
    </div>
  );
};

This example serves a single index route. Treat it as a starting point for the interface rather than as a complete replacement.

Add a Product to the Cart

Build the Category tree

• buildCategoryTree turns categoryList into a list of root nodes, each with a parentId and children. A Category whose parent is absent from the list becomes a root rather than disappearing.
• selectRootCategories takes those roots, drops the ones that only became roots because their parent was absent, and sorts the remainder by orderHint.
• findCategoryNode finds a node in a tree by Category id, and returns null when the tree holds no such node.
• toCategoryView flattens a node for display. A null node yields empty values rather than null, so the result destructures without a guard.
• toProductView flattens a Product for display, and returns null for a Product that is absent.

import {
  buildCategoryTree,
  findCategoryNode,
  selectRootCategories,
  toCategoryView,
  useCatalogModuleContext,
} from 'instoreState/context/CatalogModuleContext';
import { useLocalizationContext } from 'instoreState/locale';
import React, { useEffect, useMemo } from 'react';

type Props = { activeCategoryId: string };

export const CategoryNav = ({ activeCategoryId }: Props) => {
  const { locale } = useLocalizationContext();
  const { categoryList, getCategories } = useCatalogModuleContext();

  useEffect(() => {
    getCategories().catch(() => {
      // `categoryList` is reset to an empty list on failure, so offer a retry.
    });
  }, [getCategories]);

  const categories = useMemo(
    () => buildCategoryTree(categoryList),
    [categoryList],
  );

  const rootCategories = useMemo(
    () => selectRootCategories(categories),
    [categories],
  );

  const active = toCategoryView(
    findCategoryNode(categories, activeCategoryId),
    locale,
  );

  return (
    <div>
      <h2>{active.name}</h2>
      <ul>
        {rootCategories.map((node) => (
          <li key={node.id}>{toCategoryView(node, locale).name}</li>
        ))}
      </ul>
    </div>
  );
};

Catalog behavior to account for

Products and Categories arrive as commercetools representations rather than as display models, so account for the following behavior:

• Localized fields stay localized. toProductView and toCategoryView resolve them by exact match on the active locale, with no fallback chain, and fall back to an empty string.
• toProductView selects the Price by the country subtag of the active locale, and returns priceDinero. Format that value with .toFormat() instead of reading centAmount.
• productsByCategory holds both shapes at runtime, a list per Category and a single Product per Product id, although its declared type covers only the lists. Check with Array.isArray before you treat a value from this map as a list.
• getCategoryProducts requests one page of 100 Products. A larger Category is truncated without an error.
• The context keeps only the results of each response and discards the surrounding page, so no total or count is available. Track offset in your own state, and treat a full page as inconclusive rather than as proof that more Products exist. searchProducts returns 10 Products when you omit limit.
• The cache lives in the shared POS store, outlives your component, and isn't invalidated. Prices and availability stay as first loaded until the POS reloads.
• searchProducts resolves an empty result without calling the backend when the workstation isn't configured yet. An empty result is therefore not proof that no Product matches.
• Product Search must be active on the commercetools Project. See Activate the Product Search API, and Search Query Language for the query syntax that searchProducts accepts.
• The POS shell mounts the Catalog module provider above your routes. Consume the context, and don't mount a provider of your own.

Next steps

Use the following resources to finish and roll out your Catalog module:

• Build a replacement module to configure Module Federation, resolve types, and read shared POS state.
• Replace InStore POS UI modules to register the module and assign it to a location or a workstation.
• Implement the Cart module to read Cart state and render a replacement Cart.
• Implement the Customer module to read Customer state and render a replacement Customer lookup or header control.
• Run InStore POS API requests to set the API host, Project, and tenant, and to get an access token.