afv-library/skills/commerce-b2b-open-code-integration/SKILL.md

name	description	license	compatibility	metadata
commerce-b2b-open-code-integration	Integrate Salesforce B2B Commerce open source components from GitHub into B2B Commerce stores. Use when users mention "integrate open code components", "open source B2B commerce", "replace OOTB components", "forcedotcom/b2b-commerce-open-source-components", or want to add/replace commerce components with open source versions. Handles component integration, dependency resolution, and OOTB component replacement.	Apache-2.0	Requires Salesforce CLI (sf), Git, B2B Commerce license, and Experience Builder access	author version afv-library 1.0

When to Use This Skill

Use this skill when you need to:

• Integrate all open source B2B Commerce components into a store
• Replace all OOTB (out-of-the-box) components with open code equivalents
• Replace specific OOTB components with open code versions
• Add open source components to a new or existing B2B Commerce store
• Copy components with automatic dependency resolution

Specification

Overview

This skill enables integration of open source B2B Commerce components from the official Salesforce repository (https://github.com/forcedotcom/b2b-commerce-open-source-components) into existing or new B2B Commerce stores.

Three main scenarios:

1. Integrate - Add all open code components to a store (components become available in Experience Builder)
2. Replace All - Replace all OOTB components with open code equivalents in site metadata
3. Replace Specific - Replace individual OOTB components with open code equivalents

---

Prerequisites Flow

Store Selection/Creation

Step 1: Check for Existing Store or Create New

Ask user: "Would you like to work with an existing B2B store or create a new one?"

Step 2: If Creating New Store

• Prompt agent: "Create a Commerce B2B Store"
• Reference existing rules: rules/commerce/commerce-b2b-store-requirements.md
• Reference existing prompts: prompts/commerce/create-retrieve-b2b-storefront.md
• Wait for store creation to complete before proceeding

Step 3: If Selecting Existing Store

• Run: sf org list metadata --metadata-type DigitalExperienceConfig --json
• Parse response and extract fullName values
• Display list to user: "Please select a store from the following:"
• Capture user selection

Site Metadata Verification

Step 4: Check Local Site Metadata

Check if path exists: force-app/main/default/digitalExperiences/site/<selected-store-name>

Step 5: If Site Metadata NOT Present

Automatically retrieve: sf project retrieve start -m DigitalExperienceBundle:site/<selected-store-name>

Use the fullName value from Step 3.

Step 6: If Site Metadata Already Present

• Ask user: "Site metadata already exists locally. Do you want to overwrite with latest from org? (y/n)"
• If yes: Run sf project retrieve start -m DigitalExperienceBundle:site/<selected-store-name>
• If no: Proceed with existing local metadata

---

Core Tasks

Task 1: Clone Open Source Repository

Purpose: Clone the B2B Commerce open source components repository

Steps:

1. Check if repo already cloned in tmp folder: /tmp/b2b-commerce-open-source-components
2. If exists:
   • Warn user: "Repository already cloned. Cloning again will overwrite any local changes. Continue? (y/n)"
   • If no: Skip to next task
   • If yes: Remove existing and proceed
3. Clone: git clone https://github.com/forcedotcom/b2b-commerce-open-source-components /tmp/b2b-commerce-open-source-components
4. Verify clone successful

Task 2: Copy All Open Code Resources

Purpose: Copy all components and labels from repo to selected site

Source Paths (from cloned repo):

• Components: force-app/main/default/sfdc_cms__lwc/*
• Labels: force-app/main/default/sfdc_cms__label/*

Destination Paths (local project):

• Components: force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__lwc/
• Labels: force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__label/

Steps:

1. Check if destination directories already contain files
2. If files exist:
   • Warn user: "Components already exist. This will overwrite existing changes. Continue? (y/n)"
   • If no: Proceed with copying only new files (skip existing)
   • If yes: Overwrite all
3. Copy all component directories from source to destination
4. Copy all label directories from source to destination
5. Report: "Copied X components and Y label sets"

Task 3: Copy Specific Open Code Component

Purpose: Copy a single component with all its dependencies

Inputs:

• Component name (e.g., "cartBadge")

Steps:

1. Check if Component Exists

Verify source exists: /tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/<component-name>

If not found: Error and list available components

2. Check Destination

• Check if already exists: force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__lwc/<component-name>
• If exists: Ask to overwrite
• If no: Skip this component

3. Identify Dependencies

Scan the component files for:

a) HTML Dependencies: <site-*> tags

<!-- Example: <site-cart-badge-ui> -->

Pattern: Extract component name from <site-{component-name}>, component-name is kebab case, needs to be converted to camelCase

b) JavaScript Dependencies: import ... from 'site/*'

// Example: import { handleAddToCartSuccessWithToast } from 'site/productAddToCartUtils'

Pattern: Extract module name after site/

c) Label Dependencies: @salesforce/label/site.<component-name>.*

// Example: import maximumCount from '@salesforce/label/site.cartBadge.maximumCount';

Pattern: Extract component name between site. and next .

4. Copy Component and Dependencies

• Copy main component directory
• For each dependency found:
  • Copy dependent component from: sfdc_cms__lwc/<dependency-name>
  • Copy dependent labels from: sfdc_cms__label/<dependency-name> (if exists)
• Recursively resolve dependencies (dependencies may have dependencies)

5. Report:

• "Copied component: {component-name}"
• "Copied dependencies: {list of dependencies}"

Task 4: Extract All OOTB Components from Site Metadata

Purpose: Identify all OOTB components currently used in the site

Steps:

1. Scan Theme Layouts

• Search in: force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__themeLayout/*/content.json
• Parse each content.json file
• Extract values from "definition" keys

2. Scan Views

• Search in: force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__view/*/content.json
• Parse each content.json file
• Extract values from "definition" keys

3. Filter OOTB Components

Keep only components matching patterns:

• commerce_builder/*
• commerce_cart/*
• commerce/*
• commerce_my_account/*

4. Return List

Deduplicated list of OOTB component definitions

Example: ["commerce_builder:cartBadge", "commerce_builder:cartContents", "commerce/searchInput"]

Task 5: Find Specific OOTB Component in Site Metadata

Purpose: Check if a specific OOTB component is used in the site

Inputs:

• OOTB component name (e.g., "commerce_builder:cartBadge")

Steps:

1. Run Task 4 to get all OOTB components
2. Check if input component exists in the list
3. If found: Return true with locations (which content.json files)
4. If not found:
   • Inform user: "Component {name} not found in site metadata"
   • Display: "Components currently used in this site:"
   • List all found components
   • Ask: "Would you like to replace one of these instead?"

Task 6: Replace OOTB Component with Open Code Component

Purpose: Map and replace OOTB component references with open code equivalents

Component Naming Pattern:

OOTB components follow pattern: {namespace}:{componentName} Open code components follow pattern: site/{domain}{Context}[{Variant}] in camelCase

Mapping Rules:

OOTB Pattern	Open Code Pattern	Notes
commerce_builder/{name}	site/{name}	Builder components
commerce_cart/{name}	site/cart{Name}Ui	Cart runtime with Ui suffix
commerce/{name}	site/{name}Ui	Runtime components with Ui suffix
commerce/error	site/commonError	Shared utilities use "common" domain
commerce_builder/formattedCurrency	site/commonFormattedCurrency	Common utilities
commerce/formattedCurrency	site/commonFormattedCurrencyUi	Runtime with Ui suffix
commerce_my_account/myAccountLayout	site/themelayoutMyaccount	Account layouts
commerce/layoutSite	site/themelayoutSite	Layout → themelayout domain

Example Mappings:

commerce_builder:cartContents → site:cartContents
commerce_cart:items → site:cartItemsUi
commerce_builder:searchInput → site:searchInput
commerce:searchInput → site:searchInputUi
commerce:error → site:commonError
commerce_my_account:myAccountLayout → site:themelayoutMyaccount

Steps:

1. Parse OOTB Component Name

Extract namespace, category, and component name

2. Apply Mapping Rules

• Match against mapping table
• Generate open code component name

3. Verify Open Code Component Exists

• Check in cloned repo: /tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/
• Look for camelCase directory name (e.g., "cartBadge" for "site:cartBadge")

4. If Not Found

• List all available open code components from repo
• Ask user: "No direct mapping found. Would you like to select from available components?"

5. Update Site Metadata

• For each content.json file where component is found:
  • Replace "definition": "commerce_builder:cartBadge"
  • With "definition": "site:cartBadge"
• Preserve all other properties in the JSON

6. Track Changes

• Log all files modified
• Count replacements made

---

Use Case Workflows

Use Case 1: Only Integrate Open Code Components

User Intent: "Integrate open code components to my store"

Workflow:

1. Execute Prerequisites Flow
2. Execute Task 1: Clone Open Source Repository
3. Execute Task 2: Copy All Open Code Resources
4. Provide next steps:

✅ Integration Complete!

Next Steps:
1. Deploy components to your org:
   sf project deploy start -d force-app/main/default/digitalExperiences/site/<store-name>

2. Open Experience Builder:
   - Navigate to your store in Experience Builder
   - The new components will appear in the component palette
   - Drag and drop them into your pages
   - Configure and test each component

3. Publish your site when ready

Use Case 2: Replace All OOTB Components

User Intent: "Replace all OOTB components with open code versions"

Workflow:

1. Execute Prerequisites Flow
2. Execute Task 1: Clone Open Source Repository
3. Execute Task 2: Copy All Open Code Resources
4. Execute Task 4: Extract All OOTB Components
5. For each OOTB component found:
   • Execute Task 6: Replace OOTB Component
   • If successful: Log replacement
   • If mapping not found: Log warning and continue
6. Report summary:

✅ Replacement Complete!

Summary:
- Total OOTB components found: X
- Successfully replaced: Y
- Could not map: Z (list them)

Modified files:
- List of all content.json files changed

Next Steps:
1. Review changes:
   git diff force-app/main/default/digitalExperiences/site/<store-name>

2. Deploy to org:
   sf project deploy start -d force-app/main/default/digitalExperiences/site/<store-name>

3. Test the store thoroughly in Experience Builder

Use Case 3: Replace Specific Component

User Intent: "Replace cartBadge with open code version"

Workflow:

1. Execute Prerequisites Flow
2. Execute Task 1: Clone Open Source Repository
3. Extract component name from user intent (e.g., "cartBadge")
4. Determine OOTB format:
   • If user provides "commerce_builder:cartBadge" → use as-is
   • If user provides "cartBadge" → try common patterns:
     • First try: commerce_builder:cartBadge
     • Then try: commerce_cart:cartBadge
     • Then try: commerce:cartBadge
5. Execute Task 5: Find Specific OOTB Component
6. If found:
   • Execute Task 6: Replace OOTB Component
   • Determine open code component name from mapping
   • Execute Task 3: Copy Specific Open Code Component
7. Report:

✅ Component Replacement Complete!

Replaced: commerce_builder:cartBadge → site:cartBadge

Copied components:
- cartBadge (main)
- cartBadgeUi (dependency)
- productAddToCartUtils (dependency)

Copied labels:
- cartBadge labels

Modified files:
- List of content.json files updated

Next Steps:
1. Review changes and deploy:
   sf project deploy start -d force-app/main/default/digitalExperiences/site/<store-name>

2. Test the component in Experience Builder

---

Error Handling

Common Errors and Responses

1. Store Not Found

• Message: "Store '{name}' not found in org. Would you like to see available stores?"
• Action: List stores again

2. Component Not Found in Repo

• Message: "Component '{name}' not found in open source repo."
• Action: List available components from repo

3. Component Not Used in Site

• Message: "Component '{name}' is not currently used in this site."
• Action: Show components that are used

4. No OOTB Components Found

• Message: "No OOTB commerce components found in site metadata. The site may already be using open code components."
• Action: Offer to integrate all components instead

5. Git Clone Failed

• Message: "Failed to clone repository. Check internet connection."
• Action: Retry or abort

6. File Copy Failed

• Message: "Failed to copy files. Check file permissions."
• Action: Show error details and abort

7. No Mapping Found

• Message: "No direct mapping found for '{ootb-component}' to open code component."
• Action: Show available components and ask user to manually select

---

Verification Checklist

Before completing the integration, verify:

Store Setup

• Store has been selected or created successfully
• Site metadata has been retrieved to local project
• Site metadata path exists and is accessible

Repository

• Open source repository cloned successfully to /tmp/b2b-commerce-open-source-components
• Repository contains expected directories: sfdc_cms__lwc and sfdc_cms__label

Component Integration

• Components copied to correct destination path
• Labels copied to correct destination path
• All dependencies identified and copied (if specific component)
• No file permission errors during copy

Component Replacement (if applicable)

• All OOTB components identified correctly
• Mapping applied correctly for each component
• content.json files updated with new component definitions
• No JSON syntax errors introduced
• Original JSON structure preserved (only definition value changed)

Deployment Readiness

• All files are in correct directory structure
• No git conflicts or unstaged changes blocking deployment
• Deployment command provided to user
• User informed about testing requirements

---

Anti-Patterns to Avoid

❌ DO NOT:

• Copy components without checking for existing files first
• Modify component code or labels from the open source repo
• Replace components without verifying they exist in site metadata
• Skip dependency resolution for specific component copies
• Deploy without user confirmation
• Continue on error without informing user
• Clone repository multiple times unnecessarily
• Modify content.json structure beyond the definition value
• Add components to wrong site directory
• Skip verification of open code component existence before replacement

✅ DO:

• Always warn before overwriting existing files
• Always verify paths and existence before operations
• Always inform user of next steps
• Always provide clear error messages
• Always track and report changes made
• Always preserve JSON structure when updating metadata
• Always resolve dependencies recursively
• Always verify mappings exist before replacement