@salesforce/storefront-next-dev 0.1.0

package/dist/configs/react-router.config.d.ts

@@ -0,0 +1,13 @@
+import { Preset } from "@react-router/dev/config";
+
+//#region src/configs/react-router.config.d.ts
+
+/**
+ * Storefront Next preset for React Router configuration.
+ * This preset enforces standard configuration for SFCC Storefront Next applications.
+ * Users cannot override these values - they will be validated and an error will be thrown if modified.
+ */
+declare function storefrontNextPreset(): Preset;
+//#endregion
+export { storefrontNextPreset };
+//# sourceMappingURL=react-router.config.d.ts.map

package/dist/configs/react-router.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-router.config.d.ts","names":[],"sources":["../../src/configs/react-router.config.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAsBgB,oBAAA,CAAA,GAAwB"}

package/dist/configs/react-router.config.js

@@ -0,0 +1,36 @@
+//#region src/configs/react-router.config.ts
+/**
+* Storefront Next preset for React Router configuration.
+* This preset enforces standard configuration for SFCC Storefront Next applications.
+* Users cannot override these values - they will be validated and an error will be thrown if modified.
+*/
+function storefrontNextPreset() {
+	const presetConfig = {
+		appDirectory: "./src",
+		buildDirectory: "build",
+		routeDiscovery: { mode: "initial" },
+		serverModuleFormat: "cjs",
+		ssr: true,
+		future: {
+			v8_middleware: true,
+			v8_viteEnvironmentApi: true
+		}
+	};
+	return {
+		name: "storefront-next-preset",
+		reactRouterConfig: () => presetConfig,
+		reactRouterConfigResolved: ({ reactRouterConfig }) => {
+			const errors = [];
+			if (reactRouterConfig.routeDiscovery?.mode !== presetConfig.routeDiscovery.mode) errors.push(`routeDiscovery.mode: expected "${presetConfig.routeDiscovery.mode}", got "${reactRouterConfig.routeDiscovery?.mode}"`);
+			if (reactRouterConfig.serverModuleFormat !== presetConfig.serverModuleFormat) errors.push(`serverModuleFormat: expected "${presetConfig.serverModuleFormat}", got "${reactRouterConfig.serverModuleFormat}"`);
+			if (reactRouterConfig.ssr !== presetConfig.ssr) errors.push(`ssr: expected ${presetConfig.ssr}, got ${reactRouterConfig.ssr}`);
+			if (reactRouterConfig.future?.v8_middleware !== presetConfig.future.v8_middleware) errors.push(`future.v8_middleware: expected ${presetConfig.future.v8_middleware}, got ${reactRouterConfig.future?.v8_middleware}`);
+			if (reactRouterConfig.future?.v8_viteEnvironmentApi !== presetConfig.future.v8_viteEnvironmentApi) errors.push(`future.v8_viteEnvironmentApi: expected ${presetConfig.future.v8_viteEnvironmentApi}, got ${reactRouterConfig.future?.v8_viteEnvironmentApi}`);
+			if (errors.length > 0) throw new Error(`Storefront Next preset configuration was overridden. The following values must not be modified:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+		}
+	};
+}
+
+//#endregion
+export { storefrontNextPreset };
+//# sourceMappingURL=react-router.config.js.map

package/dist/configs/react-router.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-router.config.js","names":["errors: string[]"],"sources":["../../src/configs/react-router.config.ts"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport type { Preset } from '@react-router/dev/config';\n\n/**\n * Storefront Next preset for React Router configuration.\n * This preset enforces standard configuration for SFCC Storefront Next applications.\n * Users cannot override these values - they will be validated and an error will be thrown if modified.\n */\nexport function storefrontNextPreset(): Preset {\n    const presetConfig = {\n        appDirectory: './src',\n        buildDirectory: 'build',\n        routeDiscovery: { mode: 'initial' as const },\n        serverModuleFormat: 'cjs' as const,\n        ssr: true,\n        future: {\n            v8_middleware: true,\n            v8_viteEnvironmentApi: true,\n        },\n    };\n\n    return {\n        name: 'storefront-next-preset',\n        reactRouterConfig: () => presetConfig,\n        reactRouterConfigResolved: ({ reactRouterConfig }) => {\n            // Validate that critical config values have not been overridden\n            // Note: We don't validate appDirectory and buildDirectory because they get resolved\n            // to absolute paths and we can't reliably determine the correct absolute path\n            const errors: string[] = [];\n\n            if (reactRouterConfig.routeDiscovery?.mode !== presetConfig.routeDiscovery.mode) {\n                errors.push(\n                    `routeDiscovery.mode: expected \"${presetConfig.routeDiscovery.mode}\", got \"${reactRouterConfig.routeDiscovery?.mode}\"`\n                );\n            }\n\n            if (reactRouterConfig.serverModuleFormat !== presetConfig.serverModuleFormat) {\n                errors.push(\n                    `serverModuleFormat: expected \"${presetConfig.serverModuleFormat}\", got \"${reactRouterConfig.serverModuleFormat}\"`\n                );\n            }\n\n            if (reactRouterConfig.ssr !== presetConfig.ssr) {\n                errors.push(`ssr: expected ${presetConfig.ssr}, got ${reactRouterConfig.ssr}`);\n            }\n\n            if (reactRouterConfig.future?.v8_middleware !== presetConfig.future.v8_middleware) {\n                errors.push(\n                    `future.v8_middleware: expected ${presetConfig.future.v8_middleware}, got ${reactRouterConfig.future?.v8_middleware}`\n                );\n            }\n\n            if (reactRouterConfig.future?.v8_viteEnvironmentApi !== presetConfig.future.v8_viteEnvironmentApi) {\n                errors.push(\n                    `future.v8_viteEnvironmentApi: expected ${presetConfig.future.v8_viteEnvironmentApi}, got ${reactRouterConfig.future?.v8_viteEnvironmentApi}`\n                );\n            }\n\n            if (errors.length > 0) {\n                throw new Error(\n                    `Storefront Next preset configuration was overridden. The following values must not be modified:\\n${errors.map((e) => `  - ${e}`).join('\\n')}`\n                );\n            }\n        },\n    };\n}\n"],"mappings":";;;;;;AAsBA,SAAgB,uBAA+B;CAC3C,MAAM,eAAe;EACjB,cAAc;EACd,gBAAgB;EAChB,gBAAgB,EAAE,MAAM,WAAoB;EAC5C,oBAAoB;EACpB,KAAK;EACL,QAAQ;GACJ,eAAe;GACf,uBAAuB;GAC1B;EACJ;AAED,QAAO;EACH,MAAM;EACN,yBAAyB;EACzB,4BAA4B,EAAE,wBAAwB;GAIlD,MAAMA,SAAmB,EAAE;AAE3B,OAAI,kBAAkB,gBAAgB,SAAS,aAAa,eAAe,KACvE,QAAO,KACH,kCAAkC,aAAa,eAAe,KAAK,UAAU,kBAAkB,gBAAgB,KAAK,GACvH;AAGL,OAAI,kBAAkB,uBAAuB,aAAa,mBACtD,QAAO,KACH,iCAAiC,aAAa,mBAAmB,UAAU,kBAAkB,mBAAmB,GACnH;AAGL,OAAI,kBAAkB,QAAQ,aAAa,IACvC,QAAO,KAAK,iBAAiB,aAAa,IAAI,QAAQ,kBAAkB,MAAM;AAGlF,OAAI,kBAAkB,QAAQ,kBAAkB,aAAa,OAAO,cAChE,QAAO,KACH,kCAAkC,aAAa,OAAO,cAAc,QAAQ,kBAAkB,QAAQ,gBACzG;AAGL,OAAI,kBAAkB,QAAQ,0BAA0B,aAAa,OAAO,sBACxE,QAAO,KACH,0CAA0C,aAAa,OAAO,sBAAsB,QAAQ,kBAAkB,QAAQ,wBACzH;AAGL,OAAI,OAAO,SAAS,EAChB,OAAM,IAAI,MACN,oGAAoG,OAAO,KAAK,MAAM,OAAO,IAAI,CAAC,KAAK,KAAK,GAC/I;;EAGZ"}

package/dist/extensibility/templates/install-instructions.mdc.hbs

@@ -0,0 +1,192 @@
+These are the steps to update an existing store front application (currently opened project) with the "{{extensionName}}" extension by installing the necessary code to the destination application.
+- Follow these instructions carefully and precisely, do NOT deviate from them.
+- Mark the time it takes for each step and report them in the end.
+
+ # Step 1. Prerequisites: First make sure the current project has all the necessary files. If any requirement in the prerequisite is not met, abort the rest of this instruction.
+ <Prerequisites>
+{{#if dependencies.length}}
+ ## Dependencies Check
+ The following extensions must be installed before {{extensionName}}:
+ {{#each dependencies}}
+ - {{this.name}} ({{this.key}})
+ {{/each}}
+
+ Check if each dependency is present in `src/extensions/config.json`. If any dependency is missing, inform the user: "The extension '{{dependencies.[0].name}}' is required but not installed. Please install {{dependencies.[0].name}} first before installing {{extensionName}}." and abort this instruction.
+{{/if}}
+
+ ## Required Files
+ {{#each mergeFiles as |mergeFile|}}
+ - The file `{{mergeFile}}` exists
+ {{/each}}
+ </Prerequisites>
+
+ # Step 2. Preparations: Clone the pwa-kit repo for the specific branch into the tmp folder
+ <Preparations>
+ - Create a folder `pwa-kit-tmp` under the system's temp folder, e.g., `/tmp/pwa-kit-tmp` or 'C:/temp/pwa-kit-tmp'
+ - Clone the pwa-kit repo for the specific branch into the tmp folder: Run `git clone -b {{branch}} {{pwaRepo}} /tmp/pwa-kit-tmp`
+ </Preparations>
+
+ # Step 3. Copy:
+ <Copy>
+ {{#each copy as |copy|}}
+ {{#if copy.isDirectory}}
+ - From the cloned pwa-kit folder, copy `{{copy.src}}` folder into the current directory's `{{copy.dest}}` folder.
+ {{else}}
+ - From the cloned pwa-kit folder, copy `{{copy.src}}` file into the current directory's `{{copy.dest}}` file.
+ {{/if}}
+ {{/each}}
+  </Copy>
+
+ # Step 4. Merge. Apply the following code changes to the files specified. Skip a step if the code change has already been applied.
+ <Merge>
+ - Go through the following source files in /tmp/pwa-kit-tmp one by one, then perform the following instructions with the marker value "{{markerValue}}":
+ {{#each mergeFiles as |mergeFile|}}
+    - `{{mergeFile}}`
+ {{/each}}
+
+    <MergeInstructions>
+    Your job is find ALL the code snippets marked by special comment markers from a source file, and insert them into the destination file, which is the same file under the current project.
+
+    There are two types of comment markers:
+    1. A single line comment marker: "@sfdc-extension-line <marker value>". It is a single line comment that contains the string "@sfdc-extension-line" and a marker value, separated by a space, for example, "@sfdc-extension-line SFDC_EXT_STORE_LOCATOR".
+    2. A pair of block comment markers: "@sfdc-extension-block-start <marker value>" and "@sfdc-extension-block-end <marker value>". They are two separate comment lines that marks the start and end of a code block, with the same marker value, for example, "@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR" and "@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR".
+
+    # Step 1
+    1.1 Make a copy of the original source file before it's modified, with the ".original" extension. For example "src/components/footer/index.tsx" is copied to "src/components/footer/index.tsx.original"
+
+    # Step 2
+    There may be multiple code snippets marked by the same line marker value. Perform the action in these steps from the beginning of the source file:
+    2.1. Search for the line marker with the given marker value, e.g., "@sfdc-extension-line SFDC_EXT_STORE_LOCATOR".
+    2.2. If found, copy the comment line and the immediate line below it,
+    2.3. Insert them into the destination file at the same or similar location where the code was found in the source file.
+    2.4. Repeat the steps 2.1-2.3 from the next line until no more matching comment markers are found.
+
+    # Step 3
+    There may be multiple code snippets marked by the same block marker value. Perform the action in these steps from the beginning of the source file:
+    3.1. Search for the beginning comment marker with the given marker value, e.g., "@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR".
+    3.2. If found, search for the ending comment marker with the given marker value, e.g., "@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR".
+    3.3. If found, copy the comment lines and the code block between them,
+    3.4. Insert them into the destination file at the same or similar location where the code was found in the source file.
+    3.5. Repeat the steps 3.1-3.4 from the next line until no more matching block comment markers are found.
+
+    Do NOT include code marked by a different marker.
+    Do NOT modify any code unrelated to the marked code.
+
+    For example, when the comment marker is "@sfdc-extension-line SFDC_EXT_STORE_LOCATOR".
+
+    Source file:
+    ```javascript
+    const Header = ({
+        children,
+        onMenuClick = noop,
+        onMyAccountClick = noop,
+        onLogoClick = noop,
+        onMyCartClick = noop,
+        //@sfdc-extension-line SFDC_EXT_WISHLIST
+        onWishlistClick = noop,
+        // @sfdc-extension-line SFDC_EXT_STORE_LOCATOR
+        onStoreLocatorClick = noop,
+        ...props
+    })
+    ```
+
+    Destination file:
+    ```javascript
+    const Header = ({
+        children,
+        onMenuClick = noop,
+        onMyAccountClick = noop,
+        onLogoClick = noop,
+        onMyCartClick = noop,
+        ...props
+    })
+    ```
+
+    Output:
+    ```javascript
+    const Header = ({
+        children,
+        onMenuClick = noop,
+        onMyAccountClick = noop,
+        onLogoClick = noop,
+        onMyCartClick = noop,
+        // @sfdc-extension-line SFDC_EXT_STORE_LOCATOR
+        onStoreLocatorClick = noop,
+        ...props
+    })
+    ```
+    Note that in the destination file, there is no code snippet marked by the comment marker "@sfdc-extension-line SFDC_EXT_WISHLIST", because the marker value is SFDC_EXT_STORE_LOCATOR, not SFDC_EXT_WISHLIST.
+
+    Another example, when a block of code is marked with the beginning comment marker "@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR" and ending marker "@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR".
+
+    Source file:
+    ```javascript
+    logOut: formatMessage( {
+        defaultMessage: 'Log out',
+        id: 'header.popover.action.log_out'
+    })
+    //@sfdc-extension-block-start SFDC_EXT_WISHLIST
+    wishlist: formatMessage( {
+        defaultMessage: 'Wishlist',
+        id: 'header.button.assistive_msg.wishlist'
+    })
+    //@sfdc-extension-block-end SFDC_EXT_WISHLIST
+    //@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR
+    storeLocator: formatMessage( {
+        defaultMessage: 'Store Locator',
+        id: 'header.button.assistive_msg.store_locator'
+    })
+    //@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR
+    myCartWithItems: formatMessage( {
+        {
+            id: 'header.button.assistive_msg.my_cart_with_num_items',
+            defaultMessage: 'My cart, number of items: {numItems}'
+        },
+        {numItems: totalItems}
+    })
+    ```
+
+    Destination file:
+    ```javascript
+    logOut: formatMessage({
+        defaultMessage: 'Log out',
+        id: 'header.popover.action.log_out'
+    })
+    myCartWithItems: formatMessage( {
+        {
+            id: 'header.button.assistive_msg.my_cart_with_num_items',
+            defaultMessage: 'My cart, number of items: {numItems}'
+        },
+        {numItems: totalItems}
+    })
+    ```
+
+    Output:
+    ```javascript
+    logOut: formatMessage({
+        defaultMessage: 'Log out',
+        id: 'header.popover.action.log_out'
+    })
+    //@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR
+    storeLocator: formatMessage({
+        defaultMessage: 'Store Locator',
+        id: 'header.button.assistive_msg.store_locator'
+    })
+    //@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR
+    myCartWithItems: formatMessage( {
+        {
+            id: 'header.button.assistive_msg.my_cart_with_num_items',
+            defaultMessage: 'My cart, number of items: {numItems}'
+        },
+        {numItems: totalItems}
+    })
+    ```
+
+    Note that in the destination file, there is no code snippet marked by the comment markers "@sfdc-extension-block-start SFDC_EXT_WISHLIST" and "@sfdc-extension-block-end SFDC_EXT_WISHLIST", because the marker value is SFDC_EXT_STORE_LOCATOR, not SFDC_EXT_WISHLIST.
+    </MergeInstructions>
+ </Merge>
+
+ # Step 5. Cleanup: Delete the `pwa-kit-tmp` folder and its contents.
+ <Cleanup>
+ From under the temp folder, delete the `pwa-kit-tmp` folder and its contents.
+ </Cleanup>

package/dist/extensibility/templates/uninstall-instructions.mdc.hbs

@@ -0,0 +1,137 @@
+These are the steps to remove the "{{extensionName}}" extension from an existing store front application (currently opened project). Follow these instructions carefully and precisely, do NOT deviate from them.
+
+ # Step 1. Prerequisites: First make sure the current project has all the necessary files. If any requirement in the prerequisite is not met, abort the rest of this instruction.
+ <Prerequisites>
+{{#each mergeFiles as |mergeFile|}}
+ - The file `{{mergeFile}}` exists
+ {{/each}}
+ </Prerequisites>
+
+# Step 2. Delete files.
+<Delete>
+{{#each copy as |copy|}}
+ {{#if copy.isDirectory}}
+ - Delete the `{{copy.dest}}` folder and all its contents.
+ {{else}}
+ - Delete the `{{copy.dest}}` file.
+ {{/if}}
+ {{/each}}
+</Delete>
+
+# Step 3. Merge. Apply the following code changes to the files specified.
+<Merge>
+ - Go through the following source files one by one, then perform the following instructions with the marker value "{{markerValue}}": 
+ {{#each mergeFiles as |mergeFile|}} 
+    - `{{mergeFile}}`
+ {{/each}}
+    
+    <MergeInstructions>
+    Your job is find ALL the code snippets marked by special comment markers in the given source file and remove them.
+
+    There are two types of comment markers:
+    1. A single line comment marker: "@sfdc-extension-line <marker value>". It is a single line comment that contains the string "@sfdc-extension-line" and a marker value, separated by a space, for example, "@sfdc-extension-line SFDC_EXT_STORE_LOCATOR".
+    2. A pair of block comment markers: "@sfdc-extension-block-start <marker value>" and "@sfdc-extension-block-end <marker value>". They are two separate comment lines that marks the start and end of a code block, with the same marker value, for example, "@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR" and "@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR".
+
+    # Step 1
+    There may be multiple code snippets marked by the same line marker value. Perform the action in these steps from the beginning of the source file:
+    1.1. Search for the line marker with the given marker value, e.g., "@sfdc-extension-line SFDC_EXT_STORE_LOCATOR".
+    1.2. If found, remove the comment line and the immediate line below it,
+    1.3. Repeat the steps 1.1-1.2 from the next line until no more matching comment markers are found.
+
+    # Step 2
+    There may be multiple code snippets marked by the same block marker value. Perform the action in these steps from the beginning of the source file:
+    2.1. Search for the beginning comment marker with the given marker value, e.g., "@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR".
+    2.2. If found, search for the ending comment marker with the given marker value, e.g., "@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR".
+    2.3. If found, remove the comment lines and the code block between them.
+    2.4. Repeat the steps 2.1-2.3 from the next line until no more matching block comment markers are found.
+
+    Do NOT remove code marked by a different marker.
+    Do NOT modify any code unrelated to the marked code.
+
+    For example, when the comment marker is "@sfdc-extension-line SFDC_EXT_STORE_LOCATOR".
+
+    Input:
+    ```javascript
+    const Header = ({
+        children,
+        onMenuClick = noop,
+        onMyAccountClick = noop,
+        onLogoClick = noop,
+        onMyCartClick = noop,
+        //@sfdc-extension-line SFDC_EXT_WISHLIST
+        onWishlistClick = noop,
+        // @sfdc-extension-line SFDC_EXT_STORE_LOCATOR
+        onStoreLocatorClick = noop,
+        ...props
+    })
+    ```
+
+    Output:
+    ```javascript
+    const Header = ({
+        children,
+        onMenuClick = noop,
+        onMyAccountClick = noop,
+        onLogoClick = noop,
+        onMyCartClick = noop,
+        //@sfdc-extension-line SFDC_EXT_WISHLIST
+        onWishlistClick = noop,
+        ...props
+    })
+    ```
+
+    Note that in the output file, the code snippet marked by the comment marker "@sfdc-extension-line SFDC_EXT_WISHLIST" is not removed, because the marker value is SFDC_EXT_STORE_LOCATOR, not SFDC_EXT_WISHLIST.
+
+    Another example, when a block of code is marked with the beginning comment marker "@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR" and ending marker "@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR".
+
+    Input:
+    ```javascript
+    logOut: formatMessage( {
+        defaultMessage: 'Log out',
+        id: 'header.popover.action.log_out'
+    })
+    //@sfdc-extension-block-start SFDC_EXT_WISHLIST
+    wishlist: formatMessage( {
+        defaultMessage: 'Wishlist',
+        id: 'header.button.assistive_msg.wishlist'
+    })
+    //@sfdc-extension-block-end SFDC_EXT_WISHLIST
+    //@sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR
+    storeLocator: formatMessage( {
+        defaultMessage: 'Store Locator',
+        id: 'header.button.assistive_msg.store_locator'
+    })
+    //@sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR
+    myCartWithItems: formatMessage( {
+        {
+            id: 'header.button.assistive_msg.my_cart_with_num_items',
+            defaultMessage: 'My cart, number of items: {numItems}'
+        },
+        {numItems: totalItems}
+    })
+    ```
+
+    Output:
+    ```javascript
+    logOut: formatMessage({
+        defaultMessage: 'Log out',
+        id: 'header.popover.action.log_out'
+    })
+        //@sfdc-extension-block-start SFDC_EXT_WISHLIST
+    wishlist: formatMessage( {
+        defaultMessage: 'Wishlist',
+        id: 'header.button.assistive_msg.wishlist'
+    })
+    //@sfdc-extension-block-end SFDC_EXT_WISHLIST
+    myCartWithItems: formatMessage( {
+        {
+            id: 'header.button.assistive_msg.my_cart_with_num_items',
+            defaultMessage: 'My cart, number of items: {numItems}'
+        },
+        {numItems: totalItems}
+    })
+    ```
+
+    Note that in the destination file, the code snippet marked by the comment markers "@sfdc-extension-block-start SFDC_EXT_WISHLIST" and "@sfdc-extension-block-end SFDC_EXT_WISHLIST" is not removed, because the marker value is SFDC_EXT_STORE_LOCATOR, not SFDC_EXT_WISHLIST.
+    </MergeInstructions>
+</Merge>