@salesforce/storefront-next-dev 0.1.0

package/LICENSE.txt

@@ -0,0 +1,181 @@
+Apache License Version 2.0
+
+Copyright (c) 2026 Salesforce, Inc.
+All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,302 @@
+# @salesforce/storefront-next-dev
+
+Vite plugin and deployment tools for Storefront Next integration with React Router v7 and React Server Components.
+
+> [!IMPORTANT]
+> Storefront Next is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.
+
+## Features
+
+### Vite Plugin
+
+- 🚀 **React Server Components (RSC)** support with Vite v7
+- 🛣️ **React Router v7** integration with React Router as the framework
+- 🛒 **Commerce Cloud API** proxying for development
+- 📦 **Built-in entry files** for RSC, SSR, and browser environments
+- ☁️ **Managed Runtime Optimization** for Salesforce Commerce Cloud deployment environment
+
+### CLI & Deployment Tools
+
+- **Feature Extension Management**: Keep or remove features from a template
+- **Extension LLM Instructions**: Generate LLM instructions for installing a feature
+- **Bundle Creation**: Creates TAR archives from React Router build directories
+- **Deployment**: Pushes bundles to Managed Runtime
+- **Cartridge Generation**: Generate cartridge from decorated components, page types, aspects
+- **Cartridge Deployment**: Deploy cartridges to Commerce Cloud
+- **Workspace Integration**: Seamlessly works within pnpm workspaces
+- **Automatic Configuration**: Intelligent file detection from build directory structure
+- **TypeScript**: Written in modern TypeScript with full type safety
+- **Clean API**: Minimal, focused public API with only essential exports
+- **Modern Tooling**: Built with tsdown for fast compilation
+- **Native APIs**: Uses Node.js 18+ built-in fetch (no external HTTP dependencies)
+
+## Installation
+
+```bash
+pnpm add @salesforce/storefront-next-dev
+```
+
+## Usage
+
+### Vite Plugin
+
+Add the plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import storefrontNextPlugin from '@salesforce/storefront-next-dev';
+
+export default defineConfig({
+    plugins: [
+        storefrontNextPlugin({
+            readableChunkNames: false, // optional
+        }),
+    ],
+});
+```
+
+### React Router Preset
+
+Use the React Router preset in your `react-router.config.ts`:
+
+```typescript
+import type { Config } from '@react-router/dev/config';
+import { storefrontNextPreset } from '@salesforce/storefront-next-dev/react-router-preset';
+
+export default {
+    presets: [storefrontNextPreset()],
+} satisfies Config;
+```
+
+### CLI Commands
+
+#### Create storefront
+```bash
+# Create storefront
+pnpm dlx @salesforce/storefront-next-dev create-storefront
+```
+
+#### Push bundle
+
+```bash
+# Push bundle
+pnpm sfnext push --project-directory /path/to/your/project --project-slug mrt-project-id --target mrt-target-environment
+
+# Push bundle and wait for deployment
+pnpm sfnext push --project-directory /path/to/your/project --project-slug mrt-project-id --target mrt-target-environment --wait
+
+# Push with custom message
+pnpm sfnext push --project-directory /path/to/your/project --project-slug mrt-project-id --target mrt-target-environment --message "Release v1.2.3"
+
+# Push without deployment (upload only)
+pnpm sfnext push --project-directory /path/to/your/project --project-slug mrt-project-id
+
+# With custom build directory
+pnpm sfnext push --project-directory /path/to/your/project --build-directory /custom/build/path --project-slug mrt-project-id --target mrt-target-environment
+```
+
+#### Generate extension instructions
+
+```bash
+# Generate extension instructions
+pnpm sfnext create-instructions --project-directory /path/to/your/project --extension-config /path/to/extension/config/file --extension SFDC_EXT_STORE_LOCATOR --template-repo https://github.com/SalesforceCommerceCloud/storefront-next-template.git --branch main --files /path/to/your/new/extension/files --output-dir /path/to/instruction/files
+```
+
+#### Cartridge generation and deployment instructions
+
+```bash
+# Generate cartridge metadata for your site
+pnpm sfnext generate-cartridge --project-directory /path/to/your/project
+
+# Deploy generated metadata to Commerce Cloud (uses dw.json for all settings)
+pnpm sfnext deploy-cartridge --project-directory /path/to/your/project
+
+# Deploy cartridge to Commerce Cloud (uses dw.json for all settings)
+pnpm sfnext deploy-cartridge my-cartridge.zip
+
+# Deploy with both custom instance and version
+pnpm sfnext deploy-cartridge my-cartridge.zip -i yourCommerceInstance -v custom-version
+```
+
+
+## CLI Options
+
+#### Push bundle
+
+Run `pnpm sfnext push --help` to see all available options:
+
+- `-b, --build-directory <dir>`: Build directory to push (default: auto-detected)
+- `-m, --message <message>`: Bundle message (default: git branch:commit)
+- `-s, --project-slug <slug>`: Project slug - the unique identifier for your project on Managed Runtime (required)
+- `-t, --target <target>`: Deploy target environment on Managed Runtime
+- `-w, --wait`: Wait for deployment to complete
+- `--cloud-origin <origin>`: API origin (default: https://cloud.mobify.com)
+- `-c, --credentials-file <file>`: Credentials file location
+- `-u, --user <email>`: User email for Managed Runtime
+- `-k, --key <api-key>`: API key for Managed Runtime
+
+#### Manage extensions
+
+Run `pnpm sfnext extensions list` to view the list of installed extensions
+- `-d, --project-directory`: Target project directory (default: current directory)
+
+Run `pnpm sfnext extensions install` to install a new extension
+- `-d, --project-directory`: Target project directory (default: current directory)
+- `-e, --extension`: Extension marker value (e.g. SFDC_EXT_STORE_LOCATOR)
+- `-s, --source-git-url`: Git URL of the source template project (default: "https://github.com/SalesforceCommerceCloud/storefront-next-template.git")
+- `-v, --verbose`: Verbose mode
+
+Run `pnpm sfnext extensions remove` to remove existing extensions
+- `-d, --project-directory`: Target project directory (default: current directory)
+- `-e, --extensions`: Comma-separated list of extension marker values (e.g. SFDC_EXT_STORE_LOCATOR,SFDC_EXT_INTERNAL_THEME_SWITCHER)
+- `-v, --verbose`: Verbose mode
+
+Run `pnpm sfnext extensions create` to create a new extension scaffolding
+- `-p, --project-directory`: Target project directory (default: current directory)
+- `-n, --name`: New extension name (e.g., Store Locator)
+- `-d, --description`: Description for the extension
+
+#### Generate extension instructions
+
+Run `pnpm sfnext create-instructions --help` to see all available options:
+
+- `-d, --project-directory <dir>`: Project directory
+- `-c, --extension-config <config>`: Extension config JSON file location
+- `-e, --extension <extension>`: Extension marker value (e.g. SFDC_EXT_featureA)
+- `-p, --template-repo <repo>`: Storefront template repo URL (default: https://github.com/SalesforceCommerceCloud/storefront-next-template.git)
+- `-b, --branch <branch>`: PWA repo branch (default: main)
+- `-f, --files <files...>`: Specific files to include (relative to project directory)
+- `-o, --output-dir <dir>`: Output directory (default: ./instructions)
+
+## Configuration
+
+### Automatic Configuration
+
+sfnext uses automatic configuration that detects and configures files from your build directory:
+
+- **Server files** (`ssr_only`): Files from `build/server/` directory plus `loader.js`, `ssr.js`
+- **Client files** (`ssr_shared`): Files from `build/client/` directory plus static assets
+- **Static patterns**: Common asset types (CSS, images, fonts)
+
+### Default Configuration Details
+
+The tool automatically generates the following configuration:
+
+```json
+{
+    "ssrParameters": {
+        "ssrFunctionNodeVersion": "24.x"
+    },
+    "ssrOnly": ["loader.js", "streamingHandler.mjs", "server/**/*", "!static/**/*"],
+    "ssrShared": ["client/**/*", "static/**/*", "**/*.css", "**/*.png", "**/*.jpg", "**/*.svg", "**/*.ico"]
+}
+```
+
+Response streaming is enabled by default for bundles pushed to MRT. To change this, export `MRT_BUNDLE_TYPE=ssr` during a push command (e.g. `MRT_BUNDLE_TYPE=ssr pnpm push ...`)
+
+### Key Configuration Options
+
+- **`ssrParameters`**: Runtime configuration (Node.js version, etc.)
+- **`ssrOnly`**: Files only available on server (not CDN)
+- **`ssrShared`**: Files available on both server and CDN
+- **Patterns**: Use glob patterns with `!` for exclusions
+
+## Authentication
+
+### Deploy Cartridge Command Authentication
+
+For cartridge deployment to Commerce Cloud, you need to configure credentials in `dw.json`:
+
+1. **dw.json file** (required): Create a `dw.json` file in the **storefront-next-dev package directory** with:
+   ```json
+   {
+     "username": "your-username@salesforce.com",
+     "password": "your-web-access-key",
+     "hostname": "your-instance.dx.commercecloud.salesforce.com",
+     "code-version": "code-version-from-instance-BM"
+   }
+   ```
+
+2. **Authentication**: The tool will automatically read username, password, hostname, and code-version from `dw.json` in the storefront-next-dev directory and use Basic Authentication
+
+### Cartridge Commands
+
+The cartridge commands are independent tools for working with Commerce Cloud metadata:
+
+**Generate Cartridge**: `generate-cartridge` scans your project for decorated components and creates metadata files
+- Scans `src/` directory for `@Component`, `@PageType`, and `@Aspect` decorators
+- Generates JSON metadata files in `cartridge/cartridge/experience/` directory
+- Creates separate files for components, page types, and aspects
+
+**Deploy Metadata**: `deploy-cartridge` uploads metadata directories to Commerce Cloud
+- ZIP Creation: Automatically creates a ZIP archive from the metadata directory
+- Upload: Uploads the ZIP file to Commerce Cloud using WebDAV PUT
+- Unzip: Extracts the ZIP contents on the server using WebDAV POST
+- Cleanup: Deletes the temporary ZIP file from the server using WebDAV DELETE
+
+**Automatic Cartridge Generation and Deployment on Push**
+
+You can configure the tool to automatically generate and deploy cartridge metadata before an MRT push. This keeps your Page Designer metadata in sync with component changes.
+
+To enable automatic cartridge generation and deployment:
+
+1. Open `storefront-next-dev/dist/config.js`
+2. Change `GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH` from `false` to `true`:
+
+```javascript
+// In config.ts or config.js
+export const GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH = true; // Set to true to enable
+```
+
+**Default:** `false` (manual cartridge generation/deployment via `sfnext generate-cartridge` and `sfnext deploy-cartridge`)
+
+**Prerequisites:**
+- A valid `dw.json` file must be present in the storefront-next-dev package directory with Commerce Cloud credentials (see "Deploy Cartridge Command Authentication" section above)
+
+When enabled, before each `pnpm sfnext push` command:
+1. Cartridge metadata will be automatically generated from decorated components
+2. The cartridge will be automatically deployed to Commerce Cloud
+3. The MRT push will proceed as normal
+
+If generation or deployment fails:
+- A warning is displayed with manual command suggestions
+- The MRT push still succeeds (cartridge errors don't block deployments)
+
+You can still run `pnpm sfnext generate-cartridge` and `pnpm sfnext deploy-cartridge` manually at any time.
+
+> **Note:** This feature is designed for development workflows where you want to keep Page Designer metadata in sync with your deployments. For production CI/CD pipelines, consider running `sfnext generate-cartridge` and `sfnext deploy-cartridge` as separate, explicit steps for better control and error handling.
+
+## Credentials
+
+Set up credentials in one of these ways:
+
+1. **Credentials file** (recommended): `~/.mobify`
+
+    ```json
+    {
+        "username": "your-email@example.com",
+        "api_key": "your-api-key"
+    }
+    ```
+
+2. **Command line flags**: Use `--user` and `--key` options (see CLI Options section)
+
+Get your credentials at: https://runtime.commercecloud.com/account/settings
+
+## Bundle Structure
+
+The tool creates bundles with the following structure:
+
+- **TAR Archive**: Contains all build files prefixed with `[projectSlug]/bld/`
+- **File Distribution**:
+    - `ssr_only`: Files only on server (not CDN) - includes server-side code
+    - `ssr_shared`: Files on both server and CDN - includes client assets
+- **Metadata**: Dependencies and Commerce Cloud overrides
+
+## Subpath Exports
+
+For optimal tree-shaking, use subpath exports:
+
+- `@salesforce/storefront-next-dev` - Vite plugin (default export)
+- `@salesforce/storefront-next-dev/react-router-preset` - React Router preset
+- `@salesforce/storefront-next-dev/react-router/Scripts` - React Router Scripts component

package/dist/cartridge-services/index.d.ts

@@ -0,0 +1,60 @@
+//#region src/cartridge-services/types.d.ts
+
+interface DeployResult {
+  version: string;
+}
+//#endregion
+//#region src/cartridge-services/deploy-cartridge.d.ts
+/**
+ * Deploy code to Commerce Cloud by uploading, unzipping, and cleaning up
+ *
+ * This function performs a complete code deployment workflow:
+ * 1. Uploads the archive file via WebDAV to the specified cartridge version
+ * 2. Unzips the archive on the server
+ * 3. Deletes the uploaded archive file
+ * 4. Returns the deployed version name
+ *
+ * @param instance - The Commerce Cloud instance hostname
+ * @param codeVersionName - The target code version name
+ * @param sourceDir - The local directory containing the source files to deploy
+ * @param basicAuth - Base64 encoded basic authentication credentials
+ * @returns Promise resolving to deployment result with the version name
+ * @throws Error if any step of the deployment process fails
+ */
+declare function deployCode(instance: string, codeVersionName: string, sourceDir: string, basicAuth: string): Promise<DeployResult>;
+//#endregion
+//#region src/cartridge-services/generate-cartridge.d.ts
+/**
+ * Options for generateMetadata function
+ */
+interface GenerateMetadataOptions {
+  /**
+   * Optional array of specific file paths to process.
+   * If provided, only these files will be processed and existing cartridge files will NOT be deleted.
+   * If omitted, the entire src/ directory will be scanned and all existing cartridge files will be deleted first.
+   */
+  filePaths?: string[];
+  /**
+   * Whether to run ESLint with --fix on generated JSON files to format them according to project settings.
+   * Defaults to true.
+   */
+  lintFix?: boolean;
+  /**
+   * If true, scans files and reports what would be generated without actually writing any files or deleting directories.
+   * Defaults to false.
+   */
+  dryRun?: boolean;
+}
+/**
+ * Result returned by generateMetadata function
+ */
+interface GenerateMetadataResult {
+  componentsGenerated: number;
+  pageTypesGenerated: number;
+  aspectsGenerated: number;
+  totalFiles: number;
+}
+declare function generateMetadata(projectDirectory: string, metadataDirectory: string, options?: GenerateMetadataOptions): Promise<GenerateMetadataResult>;
+//#endregion
+export { type DeployResult, type GenerateMetadataOptions, type GenerateMetadataResult, deployCode, generateMetadata };
+//# sourceMappingURL=index.d.ts.map

package/dist/cartridge-services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/cartridge-services/types.ts","../../src/cartridge-services/deploy-cartridge.ts","../../src/cartridge-services/generate-cartridge.ts"],"sourcesContent":[],"mappings":";;UAsCiB,YAAA;;;;;AAAjB;;;;ACRiB;;;;AC0pBjB;AAwBA;AA8CA;;;;;;iBDjkBe,UAAA,mFAKZ,QAAQ;;;;;AApKM;UC0pBA,uBAAA;;;AAAjB;AAwBA;AA8CA;EAGc,SAAA,CAAA,EAAA,MAAA,EAAA;EACH;;;;;;;;;;;;;;UAlDM,sBAAA;;;;;;iBA8CK,gBAAA,gEAGR,0BACX,QAAQ"}