Feat: Implement importer utility (@W-19852067@) (#236)

* implement importer Util

* update depcheck

* update depcheck

* bump size

* remove comment

Author: joeluong-sfcc

.depcheckignore

@@ -6,3 +6,8 @@
 /apis
 /docs
 /node_modules
+
+# Ignore as it dynamically imports the commerce-sdk-isomorphic package when utility is used
+/src/lib/importUtil.ts
+/lib/importUtil.cjs.js
+/lib/importUtil.js

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Use native node fetch available in node 18+ instead of `node-fetch` polyfill [#214](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/214)
 - Support subpath imports for individual APIs and named imports [#219](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/219)
+- Add importer utility for dynamic imports [#236](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/236)
 
 ## v4.0.0
 

Contributing.md

@@ -8,6 +8,10 @@ We welcome contributions to commerce-sdk-isomorphic! To ensure that your contrib
 
 ## Building
 
+> Recommended: use Yarn 1.x (1.22.22). Newer Yarn versions are not fully supported
+
+> Requirement: Java/JDK must be installed and on your PATH (OpenAPI generation depends on it).
+
 To create the SDK package:
 
 ```
@@ -27,6 +31,77 @@ $ yarn build:lib
 $ yarn test
 ```
 
+## Preview Releases
+
+### Nightly preview
+
+- Nightly preview releases run automatically from the `preview` branch every night at midnight Pacific Time (08:00 UTC).
+- The npm dist-tag is `preview`.
+- Version format is `<base>-nightly-<UTC timestamp>`, for example: `4.0.0-nightly-20251007080238`.
+
+### Merging to `preview`
+
+Before merging any changes into `preview`, SDK generation must pass locally:
+
+```
+yarn install
+yarn clean
+yarn renderTemplates
+yarn build:lib
+yarn test
+```
+
+- Verify generated output under `src/lib/<apiName>/apis/DefaultApi.ts`:
+  - New endpoints exist
+  - New parameters are present where expected
+
+If generation or build fails, fix issues before opening/merging a PR to `preview`.
+
+For guidance on adding new API features or introducing new APIs, see [Adding or Updating APIs](#adding-or-updating-apis).
+
+## Adding or Updating APIs
+
+### New API features (existing APIs)
+
+- Locate the API’s OAS directory: `apis/<api-name>-oas-<version>/`
+- Edit or replace the public OAS file (keep the same filename), for example:
+  - `apis/shopper-products-oas-1.0.37/shopper-products-oas-v1-public.yaml`
+
+### New APIs
+
+- Create a new directory: `apis/<api-name>-oas-<version>/` (e.g., `apis/shopper-test-oas-1.0.1`)
+- Add the following files:
+  - `exchange.json` (example):
+
+    ```
+    {
+      "main": "shopper-products-oas-v1-public.yaml",
+      "name": "Shopper Products OAS",
+      "groupId": "893f605e-10e2-423a-bdb4-f952f56eb6d8",
+      "assetId": "shopper-products-oas",
+      "version": "1.0.37",
+      "classifier": "oas",
+      "tags": [],
+      "descriptorVersion": "1.0.0",
+      "organizationId": "893f605e-10e2-423a-bdb4-f952f56eb6d8",
+      "apiVersion": "v1"
+    }
+    ```
+
+  - Main OAS file named `<api-name>-oas-v1-public.yaml` (e.g., `shopper-products-oas-v1-public.yaml`)
+- Update `package.json` subpath exports so consumers can import the new API directly. Add a new entry under the top-level `exports` map using lower camel case for the API name, ensuring the path to the `lib` directory is correct:
+
+  Example for a new API named `shopperTest`:
+
+  ```json
+  "exports": {
+    "./shopperTest": {
+      "import": "./lib/shopperTest.js",
+      "require": "./lib/shopperTest.cjs.js"
+    }
+  }
+  ```
+
 ## Usage
 
 An example React App is available at `./src/environment/App` directory. To use the sample application, configure these parameters in `./src/environment/config.js` file.

README.md

@@ -340,6 +340,62 @@ console.log("categoriesResult: ", categoriesResult);
 
 **NOTE: In the next major version release, path parameters will be single encoded by default**
 
+#### Dynamic Import Utility (`importUtil`)
+
+This utility enables on-demand loading of individual APIs to keep your initial bundle small and improve page performance.
+
+##### When and why to use it
+- **Slimmer initial bundle**: Only load the API you need at the moment (e.g., load `ShopperSearch` on a search page, not at app startup).
+- **Code-splitting friendly**: Uses dynamic `import()` under the hood so bundlers split APIs into separate chunks automatically.
+- **Faster startup/TTI**: Defer heavy SDK code until the user triggers a feature.
+- **Server and browser**: Works in both ESM and CommonJS environments.
+
+##### How to use
+
+1) Import the utility (and optional key type):
+
+```ts
+import { sdkImporters } from 'commerce-sdk-isomorphic/importUtil';
+import type { CommerceSdkKeyMap } from 'commerce-sdk-isomorphic/importUtil';
+```
+
+2) Dynamically load a specific API (ESM):
+
+```ts
+// inside an async function
+const { ShopperSearch } = await sdkImporters.ShopperSearch();
+
+const shopperSearch = new ShopperSearch({
+  proxy: 'https://localhost:3000',
+  parameters: {
+    clientId: '<your-client-id>',
+    organizationId: '<your-org-id>',
+    shortCode: '<your-short-code>',
+    siteId: '<your-site-id>',
+  },
+  headers: { authorization: `Bearer ${accessToken}` },
+});
+
+const result = await shopperSearch.productSearch({ parameters: { q: 'shirt' } });
+```
+
+3) CommonJS usage:
+
+```js
+const { sdkImporters } = require('commerce-sdk-isomorphic/importUtil');
+
+(async () => {
+  const { ShopperLogin } = await sdkImporters.ShopperLogin();
+  const slas = new ShopperLogin({ /* config */ });
+})();
+```
+
+##### Additional notes
+- **Subpath exports**: This utility depends on `package.json` subpath exports (e.g., `"./shopperSearch"`). When adding a new API, ensure you add matching entries; see Contributing > New APIs.
+- **Chunking behavior**: Each API becomes a separate chunk in modern bundlers. Prefer loading at route or feature boundaries.
+- **Error handling**: If a subpath export is missing or fails to load, the promise will reject. Handle with `try/catch` as needed.
+- **Naming**: Keys are PascalCase (e.g., `ShopperBasketsV2`) while subpaths are lower camel case (e.g., `shopperBasketsv2`).
+
 ## License Information
 
 The Commerce SDK Isomorphic is licensed under BSD-3-Clause license. See the [license](./LICENSE.txt) for details.

package.json

@@ -17,6 +17,10 @@
       "import": "./lib/index.esm.js",
       "require": "./lib/index.cjs.js"
     },
+    "./importUtil": {
+      "import": "./lib/importUtil.js",
+      "require": "./lib/importUtil.cjs.js"
+    },
     "./shopperBaskets": {
       "import": "./lib/shopperBaskets.js",
       "require": "./lib/shopperBaskets.cjs.js"
@@ -25,6 +29,10 @@
       "import": "./lib/shopperBasketsv2.js",
       "require": "./lib/shopperBasketsv2.cjs.js"
     },
+    "./shopperConfigurations": {
+      "import": "./lib/shopperConfigurations.js",
+      "require": "./lib/shopperConfigurations.cjs.js"
+    },
     "./shopperConsents": {
       "import": "./lib/shopperConsents.js",
       "require": "./lib/shopperConsents.cjs.js"
@@ -53,6 +61,10 @@
       "import": "./lib/shopperOrders.js",
       "require": "./lib/shopperOrders.cjs.js"
     },
+    "./shopperPayments": {
+      "import": "./lib/shopperPayments.js",
+      "require": "./lib/shopperPayments.cjs.js"
+    },
     "./shopperProducts": {
       "import": "./lib/shopperProducts.js",
       "require": "./lib/shopperProducts.cjs.js"
@@ -250,7 +262,7 @@
     },
     {
       "path": "commerce-sdk-isomorphic-with-deps.tgz",
-      "maxSize": "2.49 MB"
+      "maxSize": "2.51 MB"
     }
   ],
   "proxy": "https://SHORTCODE.api.commercecloud.salesforce.com"

rollup.config.js

@@ -111,22 +111,27 @@ const esmConfig = {
 };
 
 // Generate common dependencies files (both ESM and CJS)
-const commonDependenciesConfig = commonDependencies.flatMap(dependency => [
-  // ESM version
-  createSubpathConfig({
+const commonDependenciesConfig = commonDependencies.flatMap(dependency => {
+  const isImporterUtil = /\bimportUtil\.ts$/.test(dependency.input);
+  const esmSubpathConfig = createSubpathConfig({
     input: dependency.input,
     outputFile: dependency.file,
     name: 'CommerceSdkCommonDependencies',
     format: 'es',
-  }),
-  // CJS version
-  createSubpathConfig({
+  });
+  const cjsSubpathConfig = createSubpathConfig({
     input: dependency.input,
     outputFile: dependency.file.replace('.js', '.cjs.js'),
     name: 'CommerceSdkCommonDependencies',
     format: 'cjs',
-  }),
-]);
+  });
+  if (isImporterUtil) {
+    // Preserves dynamic subpath imports and loads on demand instead of bundling them in the file
+    esmSubpathConfig.external = id => id.startsWith('commerce-sdk-isomorphic/');
+    cjsSubpathConfig.external = id => id.startsWith('commerce-sdk-isomorphic/');
+  }
+  return [esmSubpathConfig, cjsSubpathConfig];
+});
 
 // Generate individual API files (both ESM and CJS) so developers can import them individually
 const apiConfigs = apiNames.flatMap(apiName => [

scripts/fileList.ts

@@ -36,12 +36,13 @@ const apiNames = [
 const commonDependencies = [
   {input: 'src/lib/clientConfig.ts', file: 'lib/clientConfig.js'},
   {input: 'src/lib/config.ts', file: 'lib/config.js'},
+  {input: 'src/lib/importUtil.ts', file: 'lib/importUtil.js'},
   {input: 'src/lib/responseError.ts', file: 'lib/responseError.js'},
   {input: 'src/lib/templateUrl.ts', file: 'lib/templateUrl.js'},
   {input: 'src/lib/version.ts', file: 'lib/version.js'},
 ];
 
 // Total APIs: 17
-// Total common dependencies: 5
+// Total common dependencies: 6
 
 export {apiNames, commonDependencies};

scripts/generate-oas.ts

@@ -30,6 +30,10 @@ const VERSION_TEMPLATE_LOCATION = path.join(
   __dirname,
   '../templates/version.ts.hbs'
 );
+const IMPORTER_UTIL_TEMPLATE_LOCATION = path.join(
+  __dirname,
+  '../templates/importerUtil.ts.hbs'
+);
 
 function kebabToCamelCase(str: string): string {
   return str.replace(/-([a-z])/g, (match, letter: string) =>
@@ -120,6 +124,14 @@ export function generateIndex(context: {
   fs.writeFileSync(`${TARGET_DIRECTORY}/index.ts`, generatedIndex);
 }
 
+export function generateImporterUtil(context: {
+  children: ApiSpecDetail[];
+}): void {
+  const template = fs.readFileSync(IMPORTER_UTIL_TEMPLATE_LOCATION, 'utf8');
+  const output = Handlebars.compile(template)(context);
+  fs.writeFileSync(`${TARGET_DIRECTORY}/importUtil.ts`, output);
+}
+
 export function generateVersionFile(): void {
   const version = process.env.PACKAGE_VERSION || 'unknown';
   const versionTemplate = fs.readFileSync(VERSION_TEMPLATE_LOCATION, 'utf8');
@@ -205,6 +217,7 @@ export function main(): void {
     });
 
     generateIndex({children: apiSpecDetails});
+    generateImporterUtil({children: apiSpecDetails});
     generateVersionFile();
 
     console.log(

templates/importerUtil.ts.hbs

@@ -0,0 +1,16 @@
+type CommerceSdkKeyMap =
+{{#each children}}
+  | '{{apiName}}'
+{{/each}}
+;
+
+export const sdkImporters: Record<
+  CommerceSdkKeyMap,
+  () => Promise<Record<string, unknown>>
+> = {
+{{#each children}}
+  {{apiName}}: () => import('commerce-sdk-isomorphic/{{directoryName}}'),
+{{/each}}
+};
+
+export type { CommerceSdkKeyMap };

tsconfig.json

@@ -17,6 +17,9 @@
     "forceConsistentCasingInFileNames": true,
     "module": "esnext",
     "moduleResolution": "node",
+    "paths": {
+      "commerce-sdk-isomorphic/*": ["lib/*"]
+    },
     "resolveJsonModule": true,
     "isolatedModules": true,
     "jsx": "react-jsx",