kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-07-30 11:43:26 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

update rule and sf commands

Browse Source
This commit is contained in:
nkurapati 2026-03-11 21:12:23 +05:30 committed by nkurapati-sfdx
parent 7a6b28633d
commit ec6fc8b77f
6 changed files with 364 additions and 469 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
manifest.json
View File

@ -53,21 +53,22 @@
]
},
{
"name": "Retrieve Commerce Storefront Metadata",
"path": "prompts/commerce/retrieve-commerce-storefront.md",
"description": "Download and version-control an existing B2B/B2C Commerce LWR storefront from your org after creating the Commerce Store",
"name": "Create and Retrieve B2B Commerce Storefront",
"path": "prompts/commerce/create-retrieve-b2b-storefront.md",
"description": "Interactive guide to create a Commerce B2B Store and retrieve storefront metadata",
"category": "commerce",
"tags": [
"commerce",
"b2b",
"b2c",
"scom",
"scom b2b",
"commerce b2b",
"storefront",
"lwr",
"retrieve",
"metadata"
],
"requires_setup": true,
"setup_summary": "Commerce Store must be created in the org first via Setup → Commerce → Store Administration"
"setup_summary": "Requires Commerce licenses; agent guides through store creation interactively"
},
{
"name": "Account Layout Field Enhancement",
@ -339,14 +340,15 @@
]
},
{
"name": "Commerce Store Creation Requirements",
"path": "rules/commerce/commerce-store-requirements.md",
"description": "Critical workflow for creating B2B/B2C Commerce stores and storefronts - understand the distinction between Commerce Store (runtime data) and Storefront (LWR site).",
"name": "Commerce B2B Store Creation Requirements",
"path": "rules/commerce/commerce-b2b-store-requirements.md",
"description": "Critical workflow for creating B2B Commerce stores - understand Store vs Storefront distinction",
"category": "commerce",
"tags": [
"commerce",
"b2b",
"b2c",
"scom",
"scom b2b",
"commerce b2b",
"store",
"storefront",
"lwr",

96
prompts/commerce/README.md
View File

@ -1,6 +1,6 @@
# Commerce Prompts
Prompts for building and managing Salesforce B2B Commerce and B2C Commerce storefronts.
Prompts for building and managing Salesforce B2B Commerce storefronts.
## Overview
@ -33,58 +33,65 @@ Commerce consists of two distinct but connected parts:
### Correct Workflow
> See full interactive flow in `create-retrieve-b2b-storefront.md`
```bash
# 1. Create Commerce Store in org (via UI)
# Setup → Commerce → Store Administration → Create Store
# Setup → Commerce → Stores → Create Store
# 2. Retrieve the auto-generated storefront metadata
sf project retrieve start --metadata ExperienceBundle:My_Store_Name
# 2. List available storefronts
sf org list metadata --metadata-type DigitalExperienceConfig
# 3. Customize with additional LWCs or pages
# 3. Retrieve the auto-generated storefront metadata
sf project retrieve start -m DigitalExperienceBundle:site/My_Store_Name
# 4. Customize with additional LWCs or pages
# Add custom components, modify layouts in Experience Builder
# 4. Version control and deploy
git add force-app/main/default/experiences/
# 5. Version control and deploy
git add force-app/main/default/digitalExperiences/
git commit -m "feat: add My Store storefront"
```
### ❌ Incorrect Approach
Don't manually create StorefrontName.digitalExperience-meta.xml or StorefrontName.digitalExperience-meta.xml from scratch. The Commerce setup wizard generates complex configurations that are difficult to replicate manually.
Don't manually create StorefrontName.digitalExperience-meta.xml from scratch. The Commerce setup wizard generates complex configurations that are difficult to replicate manually.
## Available Prompts
### Retrieve Commerce Storefront Metadata
**Use when:** You've created a Commerce Store in your org and want to download the storefront to version control
### Create and Retrieve B2B Commerce Storefront
**Use when:** You want to create a Commerce B2B Store and download the storefront to version control
**Prerequisites:**
- Commerce Store created via Commerce app
- Experience Cloud site exists and is associated with store
- Default org authorized with Salesforce CLI
- Commerce licenses available in org
- Experience Cloud enabled
- Salesforce CLI authorized with default org
**What it does:**
- Guides you through retrieving ExperienceBundle metadata
- Explains what files you'll get
- Provides customization next steps
- Includes deployment instructions for other orgs
- Guides through interactive 7-step workflow
- Explains Store vs Storefront concept
- Lists available Digital Experiences in org
- Retrieves ExperienceBundle metadata
- Provides customization and deployment guidance
## Related Rules
Before using these prompts, review:
**`rules/commerce/commerce-store-requirements.md`**
**`rules/commerce/commerce-b2b-store-requirements.md`**
- Explains Store vs Storefront distinction
- Details the required creation workflow
- Lists what is/isn't source-controllable
- Provides deployment checklist
- Contains agent guidance for interactive flow
## Common Scenarios
### Scenario 1: New B2B Store
```
1. Follow commerce-store-requirements.md rule
1. Follow commerce-b2b-store-requirements.md rule
2. Create Store in org via Commerce app
3. Use "Retrieve Commerce Storefront Metadata" prompt
3. Use "Create and Retrieve B2B Commerce Storefront" prompt
4. Customize with custom LWCs (hero banner, promotions)
5. Commit and deploy to other environments
```
@ -129,34 +136,32 @@ After retrieving a Commerce storefront:
```
force-app/main/default/
├── experiences/
│ └── My_B2B_Store/
│ ├── StorefrontName.digitalExperience-meta.xml # Site config
│ ├── StorefrontName.digitalExperience-meta.xml # Bundle metadata
│ ├── config/ # Store settings
│ ├── views/ # Page definitions
│ │ ├── home.json
│ │ ├── category.json # PLP
│ │ ├── product.json # PDP
│ │ ├── cart.json
│ │ └── checkout.json
│ └── routes/ # URL routing
└── lwc/
├── b2bHeroBanner/ # Custom components
├── b2bPromotionCard/
└── b2bNavHelper/
└── digitalExperiences/
└── site/
└── My_B2B_Store1/
├── My_B2B_Store1.digitalExperience-meta.xml # Bundle metadata
├── sfdc_cms__view/ # Pages
│ ├── home/
│ ├── current_cart/
│ ├── current_checkout/
│ ├── detail_*/ # PDP
│ └── list_*/ # PLP
├── sfdc_cms__route/ # URL routing
├── sfdc_cms__site/ # Site settings
├── sfdc_cms__theme/ # Theme config
└── [other sfdc_cms__* directories]
```
## Tags
Commerce prompts use these tags:
- `commerce` - General Commerce functionality
- `b2b` - B2B Commerce specific
- `b2c` - B2C Commerce specific
- `storefront` - Buyer-facing storefront
- `store` - Backend store configuration
- `scom` - Salesforce Commerce
- `scom b2b` - Salesforce Commerce B2B
- `commerce b2b` - Commerce B2B specific
- `storefront` - Buyer-facing storefront (metadata)
- `store` - Backend store configuration (data)
- `lwr` - Lightning Web Runtime sites
- `experience-cloud` - Experience Cloud/Digital Experiences
- `retrieve` - Metadata retrieval operations
- `metadata` - Source-controllable assets
@ -164,8 +169,8 @@ Commerce prompts use these tags:
**Salesforce Documentation:**
- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/)
- [B2C Commerce on Core Guide](https://help.salesforce.com/s/articleView?id=sf.comm_digital_overview.htm)
- [Experience Cloud LWR Sites](https://developer.salesforce.com/docs/platform/lwr-sites/guide/overview.html)
- [DigitalExperienceBundle Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm)
**Trailhead:**
- [B2B Commerce Basics](https://trailhead.salesforce.com/content/learn/modules/b2b-commerce-basics)
@ -174,12 +179,11 @@ Commerce prompts use these tags:
**CLI Commands:**
```bash
# List Commerce metadata
sf org list metadata --metadata-type DigitalExperience
sf org list metadata --metadata-type ExperienceBundle
sf org list metadata --metadata-type DigitalExperienceConfig
# Retrieve storefront
sf project retrieve start --metadata ExperienceBundle:StoreName
sf project retrieve start -m DigitalExperienceBundle:site/StoreName
# Deploy storefront
sf project deploy start --source-dir force-app/main/default/experiences/
sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/StoreName/
```

238
prompts/commerce/create-retrieve-b2b-storefront.md Normal file
View File

@ -0,0 +1,238 @@
---
name: Create and Retrieve B2B Commerce Storefront
description: Interactive guide to create a Commerce B2B Store and retrieve storefront metadata
tags: commerce, b2b, scom, scom b2b, commerce b2b, storefront, lwr, retrieve, metadata
category: commerce
requires_setup: true
setup_summary: Requires Commerce licenses; agent guides through store creation interactively
---
## Context
This interactive workflow guides you through creating a Commerce B2B Store in your Salesforce org and retrieving the auto-generated storefront metadata to your local repository.
**Important:** Commerce B2B consists of two components:
1. **Commerce Store (Backend)** - Runtime data configured in the org (NOT source-controllable)
2. **Storefront (Frontend)** - LWR Digital Experience site (source-controllable metadata)
The Store must be created first because it automatically generates the associated Digital Experience site.
> **See:** `rules/commerce/commerce-b2b-store-requirements.md` for detailed Store vs Storefront distinction
---
## Interactive Flow
### Step 1: Explain Commerce B2B Store Concept
**Agent should explain:**
Commerce B2B on Salesforce Core consists of two components that work together:
1. **Commerce Store (Backend)** - Runtime data configured in the org (WebStore records, buyer groups, pricing policies, payment settings). This is NOT source-controllable.
2. **Storefront (Frontend)** - LWR Digital Experience site for buyers. This IS source-controllable as metadata (ExperienceBundle).
The Store must be created in the org first because the setup wizard automatically generates the associated Digital Experience site with all necessary Commerce components configured correctly.
> **See:** `rules/commerce/commerce-b2b-store-requirements.md` for detailed Store vs Storefront distinction
---
### Step 2: Ask User to Create B2B Store
**Agent should provide these steps:**
1. In your Salesforce org, navigate to **Setup → Commerce → Stores**
- OR use the Commerce app from **App Launcher → Commerce → Create Store**
2. Click **"Create Store"** or **"Setup New Store"**
3. Select **"B2B Store"** as the store type
4. Follow the store setup wizard:
- **Store Name**: Choose a descriptive name (e.g., "My B2B Store")
- ⚠️ Important: This name determines the folder name (spaces become underscores)
- **Default Buyer Group**: Associate with Account objects
- **Price Book**: Select or create price book
- **Checkout Settings**: Configure checkout flow
5. Complete the wizard - it will automatically create:
- WebStore record
- Default buyer group and entitlement policies
- Associated Digital Experience (LWR site)
6. Optionally configure:
- Payment gateway (Stripe, Adyen, etc.)
- Tax provider (Avalara, Vertex)
- Shipping methods
**Agent should then ask:**
"Have you completed creating the B2B Store in your org? Please reply 'yes' when ready, and let me know the store name you used."
---
### Step 3: Get Confirmation from User
**Agent waits for:** User confirmation (e.g., "yes") and store name
**Agent validates:** Store name format
- No special characters
- Spaces in name will appear as underscores in folder (e.g., "My B2B Store" → "My_B2B_Store1")
**Agent acknowledges:** "Great! Let me list the available storefronts in your org..."
---
### Step 4: Run CLI Command to List LWR Sites
**Agent executes:**
```bash
sf org list metadata --metadata-type DigitalExperienceConfig
```
**Agent should:**
- Parse the output to extract site names
- Display as a numbered list for easy selection
- Explain: "The store name appears with underscores and may have a number suffix (e.g., 'My_B2B_Store1')"
**Example output format:**
```
Available Digital Experience sites:
1. My_B2B_Store1
2. Partner_Portal
3. Customer_Community
```
---
### Step 5: Let User Select Storefront
**Agent should ask:**
"Which site corresponds to your B2B Store? Enter the number or the full site name:"
**Agent validates:**
- Selection matches one of the available sites
- If unclear, ask user to confirm the exact name
**Agent confirms:** "Got it! I'll retrieve the metadata for [site-name]..."
---
### Step 6: Retrieve Storefront Metadata
**Agent executes:**
```bash
sf project retrieve start -m DigitalExperienceBundle:site/<selected-store-name>
```
**Agent should:**
- Show retrieval progress
- Confirm successful retrieval
- List the retrieved directory structure
**Expected output:**
```
Retrieved: force-app/main/default/digitalExperiences/site/My_B2B_Store1/
├── My_B2B_Store1.digitalExperience-meta.xml
├── sfdc_cms__view/ (home, current_cart, detail_*, list_*, etc.)
├── sfdc_cms__site/
├── sfdc_cms__route/
└── [other sfdc_cms__* directories]
```
---
### Step 7: Inform User About Next Steps
**Agent provides:**
✅ **Storefront metadata successfully retrieved!**
**What you can do next:**
1. **Customize the storefront:**
- Add custom LWCs for unique B2B features
- Modify page layouts in Experience Builder
- Customize branding (colors, fonts, logos)
- Add content pages (About Us, Contact, etc.)
2. **Version control:**
```bash
git add force-app/main/default/digitalExperiences/
git commit -m "feat: add B2B Commerce storefront metadata"
```
3. **Deploy to other orgs:**
- First create B2B Store in target org with same name
- Then deploy the metadata:
```bash
sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/My_B2B_Store1/
```
**📚 Documentation Resources:**
- [DigitalExperienceBundle Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm)
- [DigitalExperienceBundle Site](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle_site.htm)
- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/)
**🎯 For Advanced Customization:**
See `rules/commerce/commerce-b2b-store-requirements.md` for:
- B2B-specific workflow patterns
- Custom LWC development guidelines
- Multi-org deployment strategies
---
## Important Notes
### ⚠️ Commerce Store Data vs Storefront Metadata
**What IS source-controllable (Storefront):**
- ✅ ExperienceBundle metadata (this prompt)
- ✅ Custom LWCs
- ✅ Page layouts and content
- ✅ Navigation structure
**What is NOT source-controllable (Commerce Store):**
- ❌ WebStore records (store settings, buyer groups)
- ❌ Product catalog data
- ❌ Price books and pricing rules
- ❌ Entitlement policies
- ❌ Inventory data
- ❌ Payment/tax/shipping configurations
**To migrate Commerce Store data between orgs:**
- Use Data Loader or Salesforce Data APIs
- Or recreate via Commerce app UI
- Or use Commerce APIs for programmatic setup
---
## Troubleshooting
### Issue: "No DigitalExperienceConfig found"
**Cause:** Store name mismatch or store not yet created
**Fix:**
1. Verify store exists: Setup → Commerce → Stores
2. Verify Experience site exists: Setup → Digital Experiences → All Sites
3. Check exact name (case-sensitive, underscores for spaces)
4. Try: `sf org list metadata --metadata-type DigitalExperienceConfig`
### Issue: "Deployment failed - Store not found"
**Cause:** Target org doesn't have a Commerce Store with matching name
**Fix:**
1. In target org, create Commerce Store with SAME NAME as source
2. Then deploy Experience metadata
### Issue: "Commerce components not rendering"
**Cause:** Store configuration missing or incorrect WebStore association
**Fix:**
1. Verify WebStore is active in target org
2. Check Experience is associated with correct WebStore
3. Verify buyer user has correct entitlements and permissions

356
prompts/commerce/retrieve-commerce-storefront.md
View File

@ -1,356 +0,0 @@
---
name: Retrieve Commerce Storefront Metadata
description: Download and version-control an existing B2B/B2C Commerce LWR storefront from your org after creating the Commerce Store
tags: commerce, b2b, b2c, storefront, lwr, retrieve, metadata, scom
category: commerce
requires_setup: true
setup_summary: Commerce Store must be created in the org first via Setup → Commerce → Stores
---
## Context
You have created a Commerce Store (B2B or B2C) in your Salesforce org using the Commerce app, and now you want to:
1. Download the auto-generated Experience Cloud storefront metadata
2. Version-control it in your repository
3. Customize it with additional LWCs or pages
**Important:** This prompt assumes you have ALREADY created the Commerce Store in your org. If you haven't done that yet, refer to the "Commerce Store Creation Requirements" rule first.
## Setup
### 1. Verify Commerce Store Exists in Org
Before proceeding, confirm your Commerce Store is set up:
```bash
# Check your connected org
sf org display --verbose
# Verify the store exists
# Go to Setup → Commerce → Stores
# You should see your store listed with status "Active"
```
**Required information:**
- Store name (e.g., "My B2B Store")
- Associated Experience Cloud site name (usually matches store name with underscores)
- Store is active and has default configurations
### 2. Find Your Experience Site Name
The Commerce setup wizard automatically creates an Experience Cloud site. To find it:
1. **In Setup:**
- Go to Setup → Digital Experiences → All Sites
- Look for the site with same name as your store (e.g., "My B2B Store")
- Note the exact folder name used in metadata (e.g., "My_B2B_Store1")
2. **Or use CLI:**
```bash
sf org list metadata --metadata-type DigitalExperience
```
## Instructions
### Step 1: List Available Digital Experiences
First, see what's available in your org:
```bash
# List all Digital Experiences
sf org list metadata --metadata-type DigitalExperience
# List all Experience Bundles (more detailed)
sf org list metadata --metadata-type ExperienceBundle
```
**Example output:**
```
DigitalExperience/My_B2B_Store
DigitalExperience/Partner_Community
```
### Step 2: Retrieve the Experience Bundle
Retrieve the complete storefront metadata for your Commerce store:
```bash
# Replace "My_B2B_Store" with your actual store name
sf project retrieve start --metadata ExperienceBundle:My_B2B_Store
# Alternative: Retrieve all experiences (if you're unsure of the name)
sf project retrieve start --metadata ExperienceBundle
```
**What this retrieves:**
```
force-app/main/default/digitalExperiences/site/StorefrontName/
├── StorefrontName.digitalExperience-meta.xml # Digital Experience Bundle metadata
├── sfdc_cms__appPage/ # App page configuration
├── sfdc_cms__brandingSet/ # Branding assets
├── sfdc_cms__label/ # Labels and translations
├── sfdc_cms__languageSettings/ # Language configuration
├── sfdc_cms__lwc/ # Lightning Web Components (custom)
├── sfdc_cms__mobilePublisherConfig/ # Mobile configuration
├── sfdc_cms__route/ # URL routing configuration
├── sfdc_cms__site/ # Site settings
├── sfdc_cms__styles/ # CSS styles
├── sfdc_cms__theme/ # Theme configuration
├── sfdc_cms__themeLayout/ # Theme layouts
└── sfdc_cms__view/ # Page definitions (views)
├── home/ # Homepage
├── current_cart/ # Shopping cart page
├── current_checkout/ # Checkout page
├── detail_*/ # Product Detail Pages (PDP)
├── list_*/ # Product List Pages (PLP)
├── order/ # Order confirmation
├── global_search/ # Search results
└── [other pages...]
```
**Example:** For a store named "My B2B Store", the folder would be:
```
force-app/main/default/digitalExperiences/site/My_B2B_Store1/
├── My_B2B_Store1.digitalExperience-meta.xml
└── [subdirectories as shown above]
```
### Step 3: Verify Retrieved Files
Check that the metadata was retrieved successfully:
```bash
# List the experience files
ls -la force-app/main/default/digitalExperiences/My_B2B_Store1/
# Check the digitalExperience metadata file
cat force-app/main/default/digitalExperiences/site/My_B2B_Store1/My_B2B_Store1.digitalExperience-meta.xml
```
**Expected content in digitalExperience-meta.xml:**
```xml
<?xml version="1.0" encoding="UTF-8"?>
<DigitalExperienceBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<label>My B2B Store</label>
<modules>...</modules>
</DigitalExperienceBundle>
```
### Step 4: Inspect Commerce Pages
Review the out-of-box Commerce pages:
```bash
# List all views (pages)
ls force-app/main/default/digitalExperiences/site/My_B2B_Store1/sfdc_cms__view/
# View a product detail page directory
ls force-app/main/default/digitalExperiences/site/My_B2B_Store1/sfdc_cms__view/detail_*/
```
**Key Commerce pages you'll find in sfdc_cms__view/:**
- **home/** - Homepage with hero banner, featured products
- **list_*/** - Product List Pages (PLP) with filters, facets
- **detail_*/** - Product Detail Pages (PDP) with images, add-to-cart
- **current_cart/** - Shopping cart with quantity updates, remove items
- **current_checkout/** - Multi-step checkout flow (shipping, payment, review)
- **global_search/** - Search results page
- **addresses/** - Buyer address management (B2B)
- **order/** - Order confirmation and history
### Step 5: Commit to Version Control
Add the retrieved metadata to your repository:
```bash
# Add the experience files
git add force-app/main/default/digitalExperiences/My_B2B_Store1/
# Commit with descriptive message
git commit -m "feat: add My B2B Store commerce storefront metadata
Retrieved from org after creating Commerce Store via Setup.
Includes home, category, product, cart, checkout pages with
out-of-box Commerce components."
# Push to remote
git push origin main
```
## Testing & Verification
### 1. Test Retrieval in a Scratch Org
**Important:** You cannot deploy Commerce storefront metadata to a scratch org without first creating the Commerce Store in that org.
To test in another org:
```bash
# 1. Create scratch org with Commerce features
sf org create scratch --definition-file config/project-scratch-def.json --alias commerce-scratch
# 2. In the scratch org Setup, create a Commerce Store with the SAME NAME as your source org
# (Setup → Commerce → Stores → Create Store)
# Use the same store name: "My B2B Store"
# 3. THEN deploy the experience metadata
sf project deploy start --source-dir force-app/main/default/digitalExperiences/My_B2B_Store1/ --target-org commerce-scratch
# 4. Open Experience Builder to verify
sf org open --target-org commerce-scratch --path /lightning/setup/SetupNetworks/home
```
### 2. Verify Components in Experience Builder
1. Open your org in Setup
2. Go to Digital Experiences → All Sites
3. Click "Builder" next to your store site
4. Verify all pages load correctly:
- Home page with hero banner
- Category page with product grid
- Product page with add-to-cart
- Cart with line items
- Checkout flow
## Customization Next Steps
Now that you have the storefront metadata, you can customize it:
### 1. Add Custom LWCs
```bash
# Create a custom promotion banner component
sf lightning generate component --type lwc \
--name b2bPromotionBanner \
--output-dir force-app/main/default/lwc
# Make it available to Experience Builder
# Edit b2bPromotionBanner.js-meta.xml:
# <isExposed>true</isExposed>
# <targets>
# <target>lightningCommunity__Page</target>
# </targets>
```
**Follow these rules for Commerce LWCs:**
- Use LDS-first approach (no Apex unless necessary)
- Expose `@api` properties for Experience Builder configuration
- Use `lightning-` base components (SLDS)
- Use `NavigationMixin` for routing
- Follow naming: `b2b[ComponentName]` or `b2c[ComponentName]`
### 2. Modify Page Layouts
1. Open Experience Builder in your org
2. Edit the page layout (e.g., add your custom component to Home)
3. Save and publish
4. Retrieve the updated metadata:
```bash
sf project retrieve start --metadata ExperienceBundle:My_B2B_Store
```
5. Commit the changes:
```bash
git add force-app/main/default/digitalExperiences/
git commit -m "feat: add custom promotion banner to home page"
```
### 3. Add Content Pages
Create additional non-commerce pages (About Us, FAQ, Contact):
1. In Experience Builder → Pages → New Page
2. Add content (text, images, forms)
3. Retrieve updated metadata
4. Commit changes
## Important Notes
### ⚠️ Commerce Store Data vs Storefront Metadata
**What IS source-controllable (Storefront):**
- ✅ ExperienceBundle metadata (this prompt)
- ✅ Custom LWCs
- ✅ Page layouts and content
- ✅ Navigation structure
**What is NOT source-controllable (Commerce Store):**
- ❌ WebStore records (store settings, buyer groups)
- ❌ Product catalog data
- ❌ Price books and pricing rules
- ❌ Entitlement policies
- ❌ Inventory data
- ❌ Payment/tax/shipping configurations
**To migrate Commerce Store data between orgs:**
- Use Data Loader or Salesforce Data APIs
- Or recreate via Commerce app UI
- Or use Commerce APIs for programmatic setup
### 🔄 Sync Workflow
After making changes in Experience Builder:
```bash
# Always retrieve after UI changes
sf project retrieve start --metadata ExperienceBundle:My_B2B_Store
# Check what changed
git diff
# Commit meaningful changes
git add force-app/main/default/digitalExperiences/
git commit -m "chore: update homepage hero banner CTA"
```
## Troubleshooting
### Issue: "No ExperienceBundle found"
**Cause:** Store name mismatch or store not yet created
**Fix:**
1. Verify store exists: Setup → Commerce → Stores
2. Verify Experience site exists: Setup → Digital Experiences → All Sites
3. Check exact name (case-sensitive, underscores for spaces)
4. Try: `sf org list metadata --metadata-type ExperienceBundle`
### Issue: "Deployment failed - Store not found"
**Cause:** Target org doesn't have a Commerce Store with matching name
**Fix:**
1. In target org, create Commerce Store with SAME NAME as source
2. Then deploy Experience metadata
### Issue: "Commerce components not rendering"
**Cause:** Store configuration missing or incorrect WebStore association
**Fix:**
1. Verify WebStore is active in target org
2. Check Experience is associated with correct WebStore
3. Verify buyer user has correct entitlements and permissions
## Follow-ups
After retrieving your storefront:
- [ ] Document your store name and configuration in README.md
- [ ] Create deployment scripts for other environments
- [ ] Set up CI/CD pipeline for storefront changes
- [ ] Create a catalog of custom LWCs for reusability
- [ ] Document Commerce Store setup steps for new environments
- [ ] Test complete buy flow (browse → PDP → cart → checkout)
## Additional Resources
**Salesforce CLI:**
- `sf project retrieve start --help`
- `sf org list metadata --help`
**Commerce Documentation:**
- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore.htm)
- [Commerce Customization Guide](https://help.salesforce.com/s/articleView?id=sf.comm_digital_customize.htm)
**Experience Cloud:**
- [LWR Sites Developer Guide](https://developer.salesforce.com/docs/platform/lwr-sites/guide/overview.html)

47
rules/commerce/README.md
View File

@ -1,6 +1,6 @@
# Commerce Rules
Rules and guardrails for developing B2B Commerce and B2C Commerce solutions on Salesforce.
Rules and guardrails for developing B2B Commerce solutions on Salesforce.
## Overview
@ -21,10 +21,12 @@ The most important concept in Commerce development is understanding the distinct
| **Deployment** | Data APIs or manual recreation | Salesforce CLI metadata deploy |
| **Examples** | Pricing policies, payment settings | Product pages, cart, checkout UI |
> **See:** `commerce-b2b-store-requirements.md` for comprehensive details
## Available Rules
### Commerce Store Creation Requirements
**`commerce-store-requirements.md`**
### Commerce B2B Store Creation Requirements
**`commerce-b2b-store-requirements.md`**
**Apply when:** Developer is creating a new Commerce storefront
@ -41,17 +43,7 @@ The most important concept in Commerce development is understanding the distinct
- Confusion about what can/cannot be source-controlled
**Required Workflow:**
```
1. Create Commerce Store (org UI)
↓
2. Store wizard creates Digital Experience
↓
3. Retrieve Experience metadata to repo
↓
4. Customize and commit
↓
5. Deploy to other orgs (after creating Store in target)
```
> See full workflow in `commerce-b2b-store-requirements.md`
## When to Apply These Rules
@ -59,17 +51,17 @@ The most important concept in Commerce development is understanding the distinct
**User says:**
- "Create a B2B Commerce store"
- "Build a B2C storefront"
- "Build a B2B storefront"
- "Set up Commerce on Core"
- "Create an LWR Commerce site"
- "Build a digital storefront"
**Agent should:**
1. ✅ Cite `rules/commerce/commerce-store-requirements.md`
2. ✅ Explain Store vs Storefront distinction
3. ✅ Guide user to create Store in org first
4. ✅ Provide CLI commands to retrieve metadata
5. ❌ **DO NOT** create StorefrontName.digitalExperience-meta.xml or StorefrontName.digitalExperience-meta.xml from scratch
1. ✅ Follow interactive flow from `prompts/commerce/create-retrieve-b2b-storefront.md`
2. ✅ Explain Store vs Storefront (link to rule file)
3. ✅ Use `sf org list metadata --metadata-type DigitalExperienceConfig` to list sites
4. ✅ Get user confirmation at each step
5. ❌ **DO NOT** create storefront files from scratch
### Trigger: User asks to deploy storefront
@ -105,7 +97,7 @@ The most important concept in Commerce development is understanding the distinct
### ❌ Deploying Without Store
```bash
# WRONG - Will fail if Store doesn't exist in target
sf project deploy start --source-dir force-app/main/default/experiences/My_Store/
sf project deploy start --source-dir force-app/main/default/digitalExperiences/My_Store/
# Error: WebStore not found
```
@ -113,7 +105,7 @@ sf project deploy start --source-dir force-app/main/default/experiences/My_Store
```bash
# 1. First create Store in target org (UI or API)
# 2. THEN deploy
sf project deploy start --source-dir force-app/main/default/experiences/My_Store/
sf project deploy start --source-dir force-app/main/default/digitalExperiences/My_Store/
```
### ❌ Trying to Version Control Store Data
@ -127,7 +119,8 @@ sf project retrieve start --metadata WebStore
```bash
# Use Data Loader, APIs, or manual recreation for Store data
# Only retrieve Experience metadata
sf project retrieve start --metadata ExperienceBundle:My_Store
sf org list metadata --metadata-type DigitalExperienceConfig
sf project retrieve start -m DigitalExperienceBundle:site/My_Store
```
## Enforcement Guidelines
@ -137,11 +130,11 @@ sf project retrieve start --metadata ExperienceBundle:My_Store
When processing Commerce-related requests:
1. **Detection Phase**
- Parse user intent for Commerce keywords (store, storefront, B2B, B2C, Commerce)
- Parse user intent for Commerce keywords (store, storefront, B2B, Commerce)
- Identify if request is for creation vs modification vs deployment
2. **Rule Application**
- Load `commerce-store-requirements.md` into context
- Load `commerce-b2b-store-requirements.md` into context
- Cite relevant sections in response
- Enforce the correct workflow order
@ -160,7 +153,7 @@ When processing Commerce-related requests:
**Before starting any Commerce work:**
- [ ] Read `rules/commerce/commerce-store-requirements.md` completely
- [ ] Read `rules/commerce/commerce-b2b-store-requirements.md` completely
- [ ] Understand Store (data) vs Storefront (metadata)
- [ ] Have org access with Commerce licenses
- [ ] Have Commerce Admin permissions
@ -231,7 +224,7 @@ When building complete Commerce solutions:
Rules work with these prompts:
- **`prompts/commerce/retrieve-commerce-storefront.md`** - Step-by-step retrieval workflow
- **`prompts/commerce/create-retrieve-b2b-storefront.md`** - Interactive 7-step retrieval workflow
- (Future) Create custom Commerce LWC components
- (Future) Commerce data seeding and migration
- (Future) Multi-store management

72
rules/commerce/commerce-store-requirements.md → rules/commerce/commerce-b2b-store-requirements.md
View File

@ -1,12 +1,12 @@
---
name: Commerce Store Creation Requirements
description: Critical workflow for creating B2B/B2C Commerce stores and storefronts - understand the distinction between Commerce Store (runtime data) and Storefront (LWR site).
tags: commerce, b2b, b2c, store, storefront, lwr, experience-cloud, rules, scom
name: Commerce B2B Store Creation Requirements
description: Critical workflow for creating B2B Commerce stores - understand Store vs Storefront distinction
tags: commerce, b2b, scom, scom b2b, commerce b2b, store, storefront, lwr, experience-cloud, rules
---
## ⚠️ CRITICAL: Commerce Store vs Storefront Distinction
When creating a Commerce B2B or B2C solution, you must understand the distinction between two separate but related components:
When creating a Commerce B2B solution, you must understand the distinction between two separate but related components:
### 1. Commerce Store (For Merchandisers)
**What it is:**
@ -51,7 +51,7 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio
## 🚫 Common Mistake: Creating Storefront Metadata from Scratch
**DO NOT** attempt to manually create Commerce storefront metadata files (StorefrontName.digitalExperience-meta.xml, StorefrontName.digitalExperience-meta.xml) from scratch in your repository.
**DO NOT** attempt to manually create Commerce storefront metadata files (StorefrontName.digitalExperience-meta.xml) from scratch in your repository.
**Why this fails:**
- Commerce storefronts have complex dependencies on the Commerce Store data
@ -61,7 +61,28 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio
---
## ✅ Required Workflow for Creating Commerce B2B/B2C Sites
## Agent Guidance: Interactive Flow Requirements
**When user asks to create Commerce storefront, agent MUST:**
1. Follow the interactive flow from `prompts/commerce/create-retrieve-b2b-storefront.md`
2. Explain the Store vs Storefront concept first
3. Guide user to create B2B Store in org with clear steps
4. Get explicit confirmation that Store was created
5. Run `sf org list metadata --metadata-type DigitalExperienceConfig` to list available sites
6. Let user select from the list (don't assume store name)
7. Retrieve with: `sf project retrieve start -m DigitalExperienceBundle:site/<store-name>`
8. Provide next steps with documentation links
**What agents should NEVER do:**
- Create .digitalExperience-meta.xml files from scratch
- Skip the Store creation step
- Assume store name without listing/confirming
- Deploy without verifying Store exists in target org
---
## ✅ Required Workflow for Creating Commerce B2B Sites
### Step 1: Create Commerce Store in the Org (MUST BE DONE FIRST)
@ -71,14 +92,12 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio
2. **Create New Store (via UI):**
- Click "Create Store" or "Setup New Store"
- Choose store type:
- **B2B Store** - For business buyers with account hierarchies, buyer groups, negotiated pricing
- **B2C Store** - For individual consumers with guest checkout
- Choose store type: **B2B Store** - For business buyers with account hierarchies, buyer groups, negotiated pricing
- Follow the store setup wizard
3. **Store Setup Wizard will create:**
- WebStore record with unique name
- Default buyer group (B2B: associated with Accounts; B2C: AllBuyers)
- Default buyer group (associated with Accounts)
- Default entitlement policies (who can see which products)
- Default price book association
- Default checkout flow configuration
@ -89,8 +108,7 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio
- Tax provider (Avalara, Vertex, manual)
- Shipping methods
- Search settings
- Guest checkout (B2C)
- Account-based features (B2B)
- Account-based features
5. **Verify Store Creation:**
- Setup → All Sites → Find your new Experience Cloud site
@ -103,13 +121,11 @@ After the Commerce Store is created in the org, retrieve the generated Experienc
```bash
# List all Digital Experiences in your org
sf project retrieve start --metadata DigitalExperience
# Or retrieve specific Experience by name
sf project retrieve start --metadata DigitalExperience:My_B2B_Store
sf org list metadata --metadata-type DigitalExperienceConfig
# Retrieve the complete ExperienceBundle
sf project retrieve start --metadata ExperienceBundle:My_B2B_Store
# Note: Salesforce appends a number suffix (e.g., "My B2B Store" becomes "My_B2B_Store1")
sf project retrieve start -m DigitalExperienceBundle:site/My_B2B_Store1
```
**What you'll get:**
@ -217,7 +233,7 @@ sf project deploy start --source-dir force-app/main/default/digitalExperiences/s
When deploying your storefront to a new org:
- [ ] Target org has Commerce licenses (B2B Commerce or B2C Commerce)
- [ ] Target org has Commerce licenses (B2B Commerce)
- [ ] Experience Cloud is enabled and domain configured
- [ ] Commerce Store has been created in target org (via Commerce app UI)
- [ ] WebStore name matches the Experience name in your metadata
@ -239,12 +255,7 @@ When deploying your storefront to a new org:
- Configure negotiated pricing and entitlement policies
- Set up account hierarchies
### For B2C Commerce:
- Configure guest checkout settings
- Set up customer registration flows
- Configure AllBuyers entitlement policy
### For Both:
### General Setup:
- Seed product catalog (Products, ProductCategory, ProductCatalog)
- Create price books and price book entries
- Configure inventory (ProductItem, LocationInventory)
@ -261,7 +272,7 @@ When deploying your storefront to a new org:
2. ✅ Instruct them to create the Commerce Store in their org first
3. ✅ Provide the Salesforce CLI retrieve commands
4. ✅ Optionally: Create custom LWCs for extending the retrieved storefront
5. ❌ DO NOT create StorefrontName.digitalExperience-meta.xml or StorefrontName.digitalExperience-meta.xml from scratch
5. ❌ DO NOT create StorefrontName.digitalExperience-meta.xml from scratch
**Acceptable to create from scratch:**
- Custom LWCs for storefront extensions (hero banners, promotions, custom product cards)
@ -281,7 +292,6 @@ When deploying your storefront to a new org:
- Setup → Commerce → Stores
- Commerce app from App Launcher → Create / Select App
- Help Article: "Set Up a B2B Commerce Store"
- Help Article: "Set Up a B2C Commerce Store"
**Storefront Customization:**
- Experience Builder → Open your store site
@ -291,13 +301,17 @@ When deploying your storefront to a new org:
**Metadata Retrieval:**
```bash
# List all retrievable metadata types
sf org list metadata --metadata-type DigitalExperience
sf org list metadata --metadata-type ExperienceBundle
sf org list metadata --metadata-type DigitalExperienceConfig
# Retrieve specific experience
sf project retrieve start --metadata ExperienceBundle:YourStoreName
sf project retrieve start -m DigitalExperienceBundle:site/YourStoreName
```
**Documentation:**
- [DigitalExperienceBundle Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm)
- [DigitalExperienceBundle Site](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle_site.htm)
- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/)
---
## 🎓 Key Takeaway