Skip to content

Hooks

To allow the user to insert custom code (e.g. for navigation after page creation), the hook pattern has been introduced.

Through this pattern it is possible to register callbacks, which are then executed by the Frontend API. It can be used as follows:

import { EcomHooks } from 'fcecom-frontend-api-client';

type OpenStoreFrontUrlPayload = {
  id: string; // ID of the element to open.
  type: string; // Type of the element to open.
  url: string; // URL of the element to open in the storefront.
};

const handleHook = (payload: OpenStorefrontUrlHookPayload) => {
  // ... Custom logic
}

api.addHook(EcomHooks.OPEN_STOREFRONT_URL, handleHook);

// To remove the registered hook, pass the exact instance
api.removeHook(EcomHooks.OPEN_STOREFRONT_URL, handleHook);

Please note that all callbacks will receive a single object containing the parameters. Further available hooks are documented in the enumeration EcomHooks in the Technical Reference documentation.

CaaS Change Stream

To ensure the storefront always reacts to up-to-date content, the Frontend API internally hooks into two TPP lifecycle events. These are handled automatically — no implementation is required on the storefront side.

  • onBeforeRequestPreviewElement (internal) — fired by TPP before navigating to a preview element (e.g. when an editor clicks an item in the ContentCreator navigation).
  • onBeforeRerenderView (internal) — fired by TPP before requesting a page re-render (e.g. after a section is edited or created). Only applies to elements of type PageRef.

For onBeforeRerenderView, the Frontend API always waits for a matching CaaS document change event via Server-Sent Events before allowing the storefront to proceed. This prevents the storefront from fetching stale content after an editor edits or creates a section.

For onBeforeRequestPreviewElement, the Frontend API only waits when a CaaS update is expected — specifically after a content change (e.g. a section was edited) or after a page was created. Plain navigation clicks in the ContentCreator (e.g. browsing to a page that has not been modified) proceed immediately without waiting.

The backend service exposes the CaaS change stream at the /caas-change-stream SSE endpoint, which it keeps alive by connecting to the CaaS WebSocket internally. No additional setup is required beyond having the backend configured with valid CaaS credentials (caasURL, tenantID, projectID, apiKey).

Timeout

If no CaaS change stream event arrives within the configured timeout, the Frontend API proceeds anyway to avoid blocking the editor indefinitely. The default timeout is 3000 ms and can be adjusted via the third constructor parameter:

const api = new EcomApi(
  'http://localhost:3001/api',
  LogLevel.DEBUG, // recommended to see which type of CaaS change stream event arrives
  5000 // wait up to 5 s for a CaaS change stream event
);
Last update: April 1, 2026