docs(headless commerce SSR): basics for commerce SSR + Remix sample

packages/headless-react/src/ssr-commerce/commerce-engine.test.tsx

@@ -49,6 +49,7 @@ describe('Headless react SSR utils', () => {
       listingEngineDefinition,
       searchEngineDefinition,
       standaloneEngineDefinition,
+      recommendationEngineDefinition,
       ...rest
     } = defineCommerceEngine({configuration: sampleConfig});
     const {

packages/headless-react/src/ssr-commerce/commerce-engine.tsx

@@ -46,12 +46,14 @@ export function defineCommerceEngine<
   >;
   type ListingContext = ContextStateType<SolutionType.listing>;
   type SearchContext = ContextStateType<SolutionType.search>;
+  type RecommendationContext = ContextStateType<SolutionType.recommendation>;
   type StandaloneContext = ContextStateType<SolutionType.standalone>;
 
   const {
     listingEngineDefinition,
     searchEngineDefinition,
     standaloneEngineDefinition,
+    recommendationEngineDefinition,
   } = defineBaseCommerceEngine({...options});
   return {
     useEngine: buildEngineHook(singletonContext),
@@ -84,5 +86,14 @@ export function defineCommerceEngine<
         singletonContext as StandaloneContext
       ),
     },
+    recommendationEngineDefinition: {
+      ...recommendationEngineDefinition,
+      StaticStateProvider: buildStaticStateProvider(
+        singletonContext as RecommendationContext
+      ),
+      HydratedStateProvider: buildHydratedStateProvider(
+        singletonContext as RecommendationContext
+      ),
+    },
   };
 }

packages/headless-react/src/ssr-commerce/index.ts

@@ -1,4 +1,4 @@
-export {defineCommerceEngine} from './commerce-engine.js';
+export * from '@coveo/headless/ssr-commerce';
 export type {ReactCommerceEngineDefinition} from './commerce-engine.js';
 export {MissingEngineProviderError} from '../errors.js';
-export * from '@coveo/headless/ssr-commerce';
+export {defineCommerceEngine} from './commerce-engine.js';

packages/headless/src/app/commerce-engine/commerce-engine.ssr.ts

@@ -1,111 +1,22 @@
 /**
  * Utility functions to be used for Commerce Server Side Rendering.
  */
-import {Action, UnknownAction} from '@reduxjs/toolkit';
-import {stateKey} from '../../app/state-key.js';
-import {buildProductListing} from '../../controllers/commerce/product-listing/headless-product-listing.js';
-import {buildSearch} from '../../controllers/commerce/search/headless-search.js';
 import type {Controller} from '../../controllers/controller/headless-controller.js';
-import {createWaitForActionMiddleware} from '../../utils/utils.js';
-import {buildControllerDefinitions} from '../commerce-ssr-engine/common.js';
+import {
+  buildFactory,
+  CommerceEngineDefinitionOptions,
+} from '../commerce-ssr-engine/factories/build-factory.js';
+import {hydratedStaticStateFactory} from '../commerce-ssr-engine/factories/hydrated-state-factory.js';
+import {hydratedRecommendationStaticStateFactory} from '../commerce-ssr-engine/factories/recommendation-hydrated-state-factory.js';
+import {fetchRecommendationStaticStateFactory} from '../commerce-ssr-engine/factories/recommendation-static-state-factory.js';
+import {fetchStaticStateFactory} from '../commerce-ssr-engine/factories/static-state-factory.js';
 import {
   ControllerDefinitionsMap,
-  InferControllerStaticStateMapFromDefinitionsWithSolutionType,
   SolutionType,
 } from '../commerce-ssr-engine/types/common.js';
-import {
-  EngineDefinition,
-  EngineDefinitionOptions,
-} from '../commerce-ssr-engine/types/core-engine.js';
-import {buildLogger} from '../logger.js';
+import {EngineDefinition} from '../commerce-ssr-engine/types/core-engine.js';
 import {NavigatorContextProvider} from '../navigatorContextProvider.js';
-import {composeFunction} from '../ssr-engine/common.js';
-import {createStaticState} from '../ssr-engine/common.js';
-import {
-  EngineStaticState,
-  InferControllerPropsMapFromDefinitions,
-} from '../ssr-engine/types/common.js';
-import {
-  CommerceEngine,
-  CommerceEngineOptions,
-  buildCommerceEngine,
-} from './commerce-engine.js';
-
-/**
- * The SSR commerce engine.
- */
-export interface SSRCommerceEngine extends CommerceEngine {
-  /**
-   * Waits for the search to be completed and returns a promise that resolves to a `SearchCompletedAction`.
-   */
-  waitForRequestCompletedAction(): Promise<Action>;
-}
-
-export type CommerceEngineDefinitionOptions<
-  TControllers extends ControllerDefinitionsMap<Controller>,
-> = EngineDefinitionOptions<CommerceEngineOptions, TControllers>;
-
-function isListingFetchCompletedAction(action: unknown): action is Action {
-  return /^commerce\/productListing\/fetch\/(fulfilled|rejected)$/.test(
-    (action as UnknownAction).type
-  );
-}
-
-function isSearchCompletedAction(action: unknown): action is Action {
-  return /^commerce\/search\/executeSearch\/(fulfilled|rejected)$/.test(
-    (action as UnknownAction).type
-  );
-}
-
-function noSearchActionRequired(_action: unknown): _action is Action {
-  return true;
-}
-
-function buildSSRCommerceEngine(
-  solutionType: SolutionType,
-  options: CommerceEngineOptions
-): SSRCommerceEngine {
-  let actionCompletionMiddleware: ReturnType<
-    typeof createWaitForActionMiddleware
-  >;
-
-  switch (solutionType) {
-    case SolutionType.listing:
-      actionCompletionMiddleware = createWaitForActionMiddleware(
-        isListingFetchCompletedAction
-      );
-      break;
-    case SolutionType.search:
-      actionCompletionMiddleware = createWaitForActionMiddleware(
-        isSearchCompletedAction
-      );
-      break;
-    default:
-      actionCompletionMiddleware = createWaitForActionMiddleware(
-        noSearchActionRequired
-      );
-  }
-
-  const commerceEngine = buildCommerceEngine({
-    ...options,
-    middlewares: [
-      ...(options.middlewares ?? []),
-      actionCompletionMiddleware.middleware,
-    ],
-  });
-
-  return {
-    ...commerceEngine,
-
-    get [stateKey]() {
-      return commerceEngine[stateKey];
-    },
-
-    waitForRequestCompletedAction() {
-      return actionCompletionMiddleware.promise;
-    },
-  };
-}
+import {CommerceEngineOptions} from './commerce-engine.js';
 
 export interface CommerceEngineDefinition<
   TControllers extends ControllerDefinitionsMap<Controller>,
@@ -139,161 +50,71 @@ export function defineCommerceEngine<
     TControllerDefinitions,
     SolutionType.standalone
   >;
-} {
-  const {controllers: controllerDefinitions, ...engineOptions} = options;
-  type Definition = CommerceEngineDefinition<
+  recommendationEngineDefinition: CommerceEngineDefinition<
     TControllerDefinitions,
-    SolutionType
+    SolutionType.recommendation
   >;
-  type BuildFunction = Definition['build'];
-  type FetchStaticStateFunction = Definition['fetchStaticState'];
-  type HydrateStaticStateFunction = Definition['hydrateStaticState'];
-  type FetchStaticStateFromBuildResultFunction =
-    FetchStaticStateFunction['fromBuildResult'];
-  type HydrateStaticStateFromBuildResultFunction =
-    HydrateStaticStateFunction['fromBuildResult'];
-  type BuildParameters = Parameters<BuildFunction>;
-  type FetchStaticStateParameters = Parameters<FetchStaticStateFunction>;
-  type HydrateStaticStateParameters = Parameters<HydrateStaticStateFunction>;
-  type FetchStaticStateFromBuildResultParameters =
-    Parameters<FetchStaticStateFromBuildResultFunction>;
-  type HydrateStaticStateFromBuildResultParameters =
-    Parameters<HydrateStaticStateFromBuildResultFunction>;
+} {
+  const {controllers: controllerDefinitions, ...engineOptions} = options;
 
-  const getOptions = () => {
-    return engineOptions;
-  };
+  const getOptions = () => engineOptions;
 
   const setNavigatorContextProvider = (
     navigatorContextProvider: NavigatorContextProvider
   ) => {
     engineOptions.navigatorContextProvider = navigatorContextProvider;
   };
 
-  const buildFactory =
-    <T extends SolutionType>(solutionType: T) =>
-    async (...[buildOptions]: BuildParameters) => {
-      const logger = buildLogger(options.loggerOptions);
-      if (!getOptions().navigatorContextProvider) {
-        logger.warn(
-          '[WARNING] Missing navigator context in server-side code. Make sure to set it with `setNavigatorContextProvider` before calling fetchStaticState()'
-        );
-      }
-      const engine = buildSSRCommerceEngine(
-        solutionType,
-        buildOptions?.extend
-          ? await buildOptions.extend(getOptions())
-          : getOptions()
-      );
-      const controllers = buildControllerDefinitions({
-        definitionsMap: (controllerDefinitions ?? {}) as TControllerDefinitions,
-        engine,
-        solutionType,
-        propsMap: (buildOptions && 'controllers' in buildOptions
-          ? buildOptions.controllers
-          : {}) as InferControllerPropsMapFromDefinitions<TControllerDefinitions>,
-      });
-
-      return {
-        engine,
-        controllers,
-      };
-    };
-
-  const fetchStaticStateFactory: (
-    solutionType: SolutionType
-  ) => FetchStaticStateFunction = (solutionType: SolutionType) =>
-    composeFunction(
-      async (...params: FetchStaticStateParameters) => {
-        const buildResult = await buildFactory(solutionType)(...params);
-        const staticState = await fetchStaticStateFactory(
-          solutionType
-        ).fromBuildResult({
-          buildResult,
-        });
-        return staticState;
-      },
-      {
-        fromBuildResult: async (
-          ...params: FetchStaticStateFromBuildResultParameters
-        ) => {
-          const [
-            {
-              buildResult: {engine, controllers},
-            },
-          ] = params;
-
-          if (solutionType === SolutionType.listing) {
-            buildProductListing(engine).executeFirstRequest();
-          } else if (solutionType === SolutionType.search) {
-            buildSearch(engine).executeFirstSearch();
-          }
-
-          const searchAction = await engine.waitForRequestCompletedAction();
-
-          return createStaticState({
-            searchAction,
-            controllers,
-          }) as EngineStaticState<
-            UnknownAction,
-            InferControllerStaticStateMapFromDefinitionsWithSolutionType<
-              TControllerDefinitions,
-              SolutionType
-            >
-          >;
-        },
-      }
+  const build = buildFactory<TControllerDefinitions>(
+    controllerDefinitions,
+    getOptions()
+  );
+  const fetchStaticState = fetchStaticStateFactory<TControllerDefinitions>(
+    controllerDefinitions,
+    getOptions()
+  );
+  const hydrateStaticState = hydratedStaticStateFactory<TControllerDefinitions>(
+    controllerDefinitions,
+    getOptions()
+  );
+  const fetchRecommendationStaticState =
+    fetchRecommendationStaticStateFactory<TControllerDefinitions>(
+      controllerDefinitions,
+      getOptions()
     );
-
-  const hydrateStaticStateFactory: (
-    solutionType: SolutionType
-  ) => HydrateStaticStateFunction = (solutionType: SolutionType) =>
-    composeFunction(
-      async (...params: HydrateStaticStateParameters) => {
-        const buildResult = await buildFactory(solutionType)(
-          ...(params as BuildParameters)
-        );
-        const staticState = await hydrateStaticStateFactory(
-          solutionType
-        ).fromBuildResult({
-          buildResult,
-          searchAction: params[0]!.searchAction,
-        });
-        return staticState;
-      },
-      {
-        fromBuildResult: async (
-          ...params: HydrateStaticStateFromBuildResultParameters
-        ) => {
-          const [
-            {
-              buildResult: {engine, controllers},
-              searchAction,
-            },
-          ] = params;
-          engine.dispatch(searchAction);
-          await engine.waitForRequestCompletedAction();
-          return {engine, controllers};
-        },
-      }
+  const hydrateRecommendationStaticState =
+    hydratedRecommendationStaticStateFactory<TControllerDefinitions>(
+      controllerDefinitions,
+      getOptions()
     );
+
   return {
     listingEngineDefinition: {
-      build: buildFactory(SolutionType.listing),
-      fetchStaticState: fetchStaticStateFactory(SolutionType.listing),
-      hydrateStaticState: hydrateStaticStateFactory(SolutionType.listing),
+      build: build(SolutionType.listing),
+      fetchStaticState: fetchStaticState(SolutionType.listing),
+      hydrateStaticState: hydrateStaticState(SolutionType.listing),
       setNavigatorContextProvider,
     } as CommerceEngineDefinition<TControllerDefinitions, SolutionType.listing>,
     searchEngineDefinition: {
-      build: buildFactory(SolutionType.search),
-      fetchStaticState: fetchStaticStateFactory(SolutionType.search),
-      hydrateStaticState: hydrateStaticStateFactory(SolutionType.search),
+      build: build(SolutionType.search),
+      fetchStaticState: fetchStaticState(SolutionType.search),
+      hydrateStaticState: hydrateStaticState(SolutionType.search),
       setNavigatorContextProvider,
     } as CommerceEngineDefinition<TControllerDefinitions, SolutionType.search>,
+    recommendationEngineDefinition: {
+      build: build(SolutionType.recommendation),
+      fetchStaticState: fetchRecommendationStaticState,
+      hydrateStaticState: hydrateRecommendationStaticState,
+      setNavigatorContextProvider,
+    } as CommerceEngineDefinition<
+      TControllerDefinitions,
+      SolutionType.recommendation
+    >,
+    // TODO KIT-3738 :  The standaloneEngineDefinition should not be async since no request is sent to the API
     standaloneEngineDefinition: {
-      build: buildFactory(SolutionType.standalone),
-      fetchStaticState: fetchStaticStateFactory(SolutionType.standalone),
-      hydrateStaticState: hydrateStaticStateFactory(SolutionType.standalone),
+      build: build(SolutionType.standalone),
+      fetchStaticState: fetchStaticState(SolutionType.standalone),
+      hydrateStaticState: hydrateStaticState(SolutionType.standalone),
       setNavigatorContextProvider,
     } as CommerceEngineDefinition<
       TControllerDefinitions,