kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-08-05 14:54:50 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add instructions to create commerce b2b store from vibes

Browse Source
This commit is contained in:
nkurapati 2026-03-08 00:52:06 +05:30
parent 7b5c4b1a76
commit 3c36149e62
5 changed files with 1134 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
manifest.json
View File

@ -1,6 +1,6 @@
{
"version": 1,
"generatedAt": "2026-02-17T21:01:05.349Z",
"generatedAt": "2026-03-07T00:00:00.000Z",
"branch": "main",
"prompts": [
{
@ -52,6 +52,23 @@
"admin"
]
},
{
"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",
"category": "commerce",
"tags": [
"commerce",
"b2b",
"b2c",
"storefront",
"lwr",
"retrieve",
"metadata"
],
"requires_setup": true,
"setup_summary": "Commerce Store must be created in the org first via Setup → Commerce → Store Administration"
},
{
"name": "Account Layout Field Enhancement",
"path": "prompts/getting-started/add-fields-pagelayout.md",
@ -321,6 +338,22 @@
"security"
]
},
{
"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).",
"category": "commerce",
"tags": [
"commerce",
"b2b",
"b2c",
"store",
"storefront",
"lwr",
"experience-cloud",
"rules"
]
},
{
"name": "LWC Development Guardrails",
"path": "rules/lwc-development/lwc-requirements.md",

185
prompts/commerce/README.md Normal file
View File

@ -0,0 +1,185 @@
# Commerce Prompts
Prompts for building and managing Salesforce B2B Commerce and B2C Commerce storefronts.
## Overview
Commerce on Core enables you to build digital storefronts using Experience Cloud (LWR sites) integrated with Commerce capabilities for product catalogs, pricing, shopping cart, checkout, and order management.
### Two-Part Architecture
Commerce consists of two distinct but connected parts:
1. **Commerce Store** (Backend - Runtime Data)
- WebStore configuration
- Buyer groups and entitlements
- Pricing policies
- Payment, tax, shipping setup
- Product catalog associations
- **Created in org via Setup → Commerce app**
- **NOT source-controllable**
2. **Storefront** (Frontend - Metadata)
- Digital Experience (LWR site)
- Page layouts and components
- Custom LWCs
- Branding and theme
- **Source-controllable as ExperienceBundle**
- **Deployable via Salesforce CLI**
## Usage Pattern
**Critical:** Always create Commerce Store in org FIRST, then retrieve the auto-generated storefront metadata.
### Correct Workflow
```bash
# 1. Create Commerce Store in org (via UI)
# Setup → Commerce → Store Administration → Create Store
# 2. Retrieve the auto-generated storefront metadata
sf project retrieve start --metadata ExperienceBundle:My_Store_Name
# 3. 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/
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.
## 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
**Prerequisites:**
- Commerce Store created via Commerce app
- Experience Cloud site exists and is associated with store
- Default org authorized with Salesforce CLI
**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
## Related Rules
Before using these prompts, review:
**`rules/commerce/commerce-store-requirements.md`**
- Explains Store vs Storefront distinction
- Details the required creation workflow
- Lists what is/isn't source-controllable
- Provides deployment checklist
## Common Scenarios
### Scenario 1: New B2B Store
```
1. Follow commerce-store-requirements.md rule
2. Create Store in org via Commerce app
3. Use "Retrieve Commerce Storefront Metadata" prompt
4. Customize with custom LWCs (hero banner, promotions)
5. Commit and deploy to other environments
```
### Scenario 2: Extend Existing Storefront
```
1. Retrieve current metadata if not already in repo
2. Create custom LWCs following LDS-first patterns
3. Add to pages in Experience Builder
4. Retrieve updated metadata
5. Commit changes
```
### Scenario 3: Multi-Org Deployment
```
1. In target org, create Commerce Store (same name as source)
2. Deploy storefront metadata from repo
3. Verify Commerce components render correctly
4. Configure org-specific settings (payment, tax, shipping)
```
## Best Practices
### ✅ Do:
- Create Commerce Store in org first (always!)
- Retrieve auto-generated storefront metadata
- Version control Experience metadata
- Use LDS-first approach for custom LWCs
- Document store configuration steps
- Test in Experience Builder before deploying
### ❌ Don't:
- Create StorefrontName.digitalExperience-meta.xml from scratch
- Deploy storefront without creating Store in target org
- Try to version control WebStore records (use data APIs)
- Skip the Commerce setup wizard
- Forget to associate Experience with WebStore
## File Structure
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/
```
## 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
- `lwr` - Lightning Web Runtime sites
- `experience-cloud` - Experience Cloud/Digital Experiences
- `retrieve` - Metadata retrieval operations
- `metadata` - Source-controllable assets
## Additional Resources
**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)
**Trailhead:**
- [B2B Commerce Basics](https://trailhead.salesforce.com/content/learn/modules/b2b-commerce-basics)
- [Build a B2B Commerce Store](https://trailhead.salesforce.com/content/learn/projects/build-a-b2b-commerce-store)
**CLI Commands:**
```bash
# List Commerce metadata
sf org list metadata --metadata-type DigitalExperience
sf org list metadata --metadata-type ExperienceBundle
# Retrieve storefront
sf project retrieve start --metadata ExperienceBundle:StoreName
# Deploy storefront
sf project deploy start --source-dir force-app/main/default/experiences/
```

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

@ -0,0 +1,356 @@
---
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)

250
rules/commerce/README.md Normal file
View File

@ -0,0 +1,250 @@
# Commerce Rules
Rules and guardrails for developing B2B Commerce and B2C Commerce solutions on Salesforce.
## Overview
Commerce rules ensure developers understand the proper workflow for creating, deploying, and maintaining Commerce storefronts. These rules prevent common mistakes and enforce best practices specific to Commerce development.
## Critical Concepts
### Store vs Storefront
The most important concept in Commerce development is understanding the distinction:
| Aspect | Commerce Store | Storefront (LWR Site) |
|--------|---------------|----------------------|
| **What** | Backend configuration & data | Frontend buyer experience |
| **Created** | Via Commerce app UI | Auto-generated by Store wizard |
| **Stored** | As data records (WebStore, BuyerGroup, etc.) | As metadata (ExperienceBundle) |
| **Source Control** | ❌ Not source-controllable | ✅ Source-controllable |
| **Deployment** | Data APIs or manual recreation | Salesforce CLI metadata deploy |
| **Examples** | Pricing policies, payment settings | Product pages, cart, checkout UI |
## Available Rules
### Commerce Store Creation Requirements
**`commerce-store-requirements.md`**
**Apply when:** Developer is creating a new Commerce storefront
**Key Enforcements:**
- ❌ **DO NOT** create storefront metadata from scratch
- ✅ **MUST** create Commerce Store in org first via Setup → Commerce
- ✅ **MUST** retrieve auto-generated Experience metadata
- ✅ **MUST** create Store in target org before deploying storefront
**Prevents:**
- Broken storefronts missing critical configurations
- Failed deployments due to missing WebStore associations
- Wasted time manually creating complex JSON structures
- 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)
```
## When to Apply These Rules
### Trigger: User asks to create Commerce storefront
**User says:**
- "Create a B2B Commerce store"
- "Build a B2C 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
### Trigger: User asks to deploy storefront
**User says:**
- "Deploy my Commerce storefront to sandbox"
- "How do I move my store to production"
- "Deploy B2B store to another org"
**Agent should:**
1. ✅ Verify Commerce Store exists in target org with same name
2. ✅ Warn that Store data must be recreated/migrated separately
3. ✅ Provide deployment commands for Experience metadata only
4. ✅ Remind about payment/tax/shipping configuration in target org
## Rule Violations to Prevent
### ❌ Creating Storefront from Scratch
```javascript
// WRONG - Don't manually create this
{
"siteType": "LWR",
"label": "My Store",
// ... hundreds of lines of complex config ...
}
```
**Why it fails:**
- Missing WebStore associations
- Incorrect Commerce component configurations
- Missing default pages and routes
- Incomplete navigation structure
### ❌ 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/
# Error: WebStore not found
```
**Correct:**
```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/
```
### ❌ Trying to Version Control Store Data
```bash
# WRONG - WebStore is data, not metadata
sf project retrieve start --metadata WebStore
# Error: WebStore is not a valid metadata type
```
**Correct:**
```bash
# Use Data Loader, APIs, or manual recreation for Store data
# Only retrieve Experience metadata
sf project retrieve start --metadata ExperienceBundle:My_Store
```
## Enforcement Guidelines
### For AI Agents / Assistants
When processing Commerce-related requests:
1. **Detection Phase**
- Parse user intent for Commerce keywords (store, storefront, B2B, B2C, Commerce)
- Identify if request is for creation vs modification vs deployment
2. **Rule Application**
- Load `commerce-store-requirements.md` into context
- Cite relevant sections in response
- Enforce the correct workflow order
3. **Guidance Phase**
- Explain Store vs Storefront distinction upfront
- Provide specific CLI commands
- Include prerequisites checklist
- Warn about common pitfalls
4. **Implementation Phase**
- Create custom LWCs only (never core storefront files)
- Follow LDS-first patterns
- Document deployment dependencies
### For Developers
**Before starting any Commerce work:**
- [ ] Read `rules/commerce/commerce-store-requirements.md` completely
- [ ] Understand Store (data) vs Storefront (metadata)
- [ ] Have org access with Commerce licenses
- [ ] Have Commerce Admin permissions
**During development:**
- [ ] Always create Store in org first
- [ ] Retrieve (never create) core storefront metadata
- [ ] Follow LDS-first patterns for custom LWCs
- [ ] Test in Experience Builder before committing
- [ ] Document Store configuration steps
**Before deployment:**
- [ ] Verify target org has Commerce licenses
- [ ] Create Store in target org with matching name
- [ ] Deploy Experience metadata only
- [ ] Configure payment/tax/shipping in target
- [ ] Test buy flow end-to-end
## Integration with Other Rules
Commerce rules work together with:
### LWC Development Guardrails
**`rules/lwc-development/lwc-requirements.md`**
When creating custom Commerce components:
- Apply LDS-first approach (no Apex unless necessary)
- Use `lightning-` base components
- Expose `@api` properties for Experience Builder
- Follow SLDS design patterns
- Use `NavigationMixin` for routing
### Spec-Driven App Development Standards
**`rules/spec-driven-dev/app-dev.md`**
When building complete Commerce solutions:
- Document store configuration requirements
- Create permission sets for Commerce users
- Follow naming conventions
- Maintain architecture documentation
## Common Questions
### Q: Can I create a Commerce storefront entirely in source control?
**A:** No. You must create the Commerce Store in the org first (via UI or API), which auto-generates the storefront. You can then retrieve and customize that storefront metadata.
### Q: What if I want to automate Store creation?
**A:** Use Commerce APIs to create WebStore records programmatically. Then retrieve the generated Experience metadata. Still don't create storefront JSON manually.
### Q: How do I migrate a Store to production?
**A:**
1. Create Store in production org (via UI or API) with same name
2. Export/import Store data (WebStore, BuyerGroup, EntitlementPolicy records)
3. Deploy Experience metadata from source control
4. Configure payment/tax/shipping in production
5. Test thoroughly before going live
### Q: Can I have multiple Stores in one org?
**A:** Yes. Each Store gets its own WebStore record and associated Experience site. Retrieve each storefront separately and organize in different directories.
## Related Prompts
Rules work with these prompts:
- **`prompts/commerce/retrieve-commerce-storefront.md`** - Step-by-step retrieval workflow
- (Future) Create custom Commerce LWC components
- (Future) Commerce data seeding and migration
- (Future) Multi-store management
## Additional Resources
**Salesforce Help:**
- [Commerce Store Administration](https://help.salesforce.com/s/articleView?id=sf.comm_store_admin.htm)
- [Commerce Setup Guide](https://help.salesforce.com/s/articleView?id=sf.comm_setup_overview.htm)
**Developer Guides:**
- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/)
- [Commerce APIs](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce.htm)
**Community:**
- [Commerce on Core Trailblazer Community](https://trailhead.salesforce.com/trailblazer-community/topics/commerce)

309
rules/commerce/commerce-store-requirements.md Normal file
View File

@ -0,0 +1,309 @@
---
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
---
## ⚠️ 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:
### 1. Commerce Store (For Merchandisers)
**What it is:**
- Runtime data and configuration created in the Salesforce org
- NOT source-controllable metadata
- Created through the Commerce app UI or Commerce APIs
**What it includes:**
- Store configuration and settings
- Default buyer groups
- Entitlement policies
- Pricing policies
- Payment, tax, and shipping configurations
- Product catalog associations
- Price book mappings
- Inventory locations
- Search index configurations
**Where it lives:**
- Data records in standard Commerce objects (WebStore, BuyerGroup, EntitlementPolicy, etc.)
- Configured via Setup → Commerce → Stores
### 2. Storefront (For Buyers)
**What it is:**
- Digital Experience (LWR site) for buyer-facing shopping experience
- Source-controllable as ExperienceBundle metadata
- Created automatically when you create a Commerce Store, or manually via Experience Builder
**What it includes:**
- ExperienceBundle metadata (StorefrontName.digitalExperience-meta.xml, routes, views, navigation)
- Lightning Web Components (product list, product detail, cart, checkout)
- Branding and theme configuration
- Page layouts and content
- Custom LWCs for unique functionality
**Where it lives:**
- `force-app/main/default/digitalExperiences/site/StorefrontName/`
- Example: `force-app/main/default/digitalExperiences/site/My_B2B_Store1/`
- Retrievable and deployable via Salesforce CLI
---
## 🚫 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.
**Why this fails:**
- Commerce storefronts have complex dependencies on the Commerce Store data
- Out-of-box Commerce components require specific configurations tied to WebStore records
- Commerce-managed components (search, PLP, PDP, cart, checkout) are generated and configured by the Commerce setup wizard
- Missing the Store-to-Storefront associations will result in non-functional pages
---
## ✅ Required Workflow for Creating Commerce B2B/B2C Sites
### Step 1: Create Commerce Store in the Org (MUST BE DONE FIRST)
1. **Access Commerce Setup:**
- Navigate to Setup → Commerce → Stores
- OR use the Commerce app from App Launcher → Create / Select App
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
- 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 entitlement policies (who can see which products)
- Default price book association
- Default checkout flow configuration
- **Associated Digital Experience (Storefront)** - This is auto-generated!
4. **Configure Store Settings:**
- Payment gateway (Stripe, Adyen, etc.)
- Tax provider (Avalara, Vertex, manual)
- Shipping methods
- Search settings
- Guest checkout (B2C)
- Account-based features (B2B)
5. **Verify Store Creation:**
- Setup → All Sites → Find your new Experience Cloud site
- The site name will match your store name (e.g., "My B2B Store" → "My_B2B_Store")
- The Experience was created automatically during Store setup
### Step 2: Retrieve Digital Experience Metadata (Storefront)
After the Commerce Store is created in the org, retrieve the generated Experience metadata:
```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
# Retrieve the complete ExperienceBundle
sf project retrieve start --metadata ExperienceBundle:My_B2B_Store
```
**What you'll get:**
```
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 structure would be:
```
force-app/main/default/digitalExperiences/site/My_B2B_Store1/
├── My_B2B_Store1.digitalExperience-meta.xml
└── [subdirectories as shown above]
```
### Step 3: Customize Storefront (Optional)
Once you have the retrieved metadata, you can:
1. **Add custom LWCs** following LDS-first patterns
2. **Modify page layouts** in Experience Builder
3. **Customize branding** (colors, fonts, logos)
4. **Add content pages** (About Us, FAQ, Terms)
5. **Configure navigation** and menus
**Important:**
- Test changes in Experience Builder before committing to source control
- Use `sf project retrieve start` after each change to sync metadata
- Deploy to other orgs using `sf project deploy start`
### Step 4: Version Control Workflow
```bash
# After creating store and retrieving metadata
git add force-app/main/default/digitalExperiences/
git commit -m "feat: add My B2B Store digital experience metadata"
# Deploy to scratch org or sandbox (replace My_B2B_Store1 with your storefront name)
sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/My_B2B_Store1
# Note: Commerce Store data must be recreated in target org first!
```
---
## 🎯 Summary: The Correct Order
```
1. ✅ Create Commerce Store in org (Setup → Commerce)
↓
2. ✅ Store wizard creates WebStore + Digital Experience
↓
3. ✅ Retrieve Experience metadata to local repo
↓
4. ✅ Customize and extend (LWCs, pages, branding)
↓
5. ✅ Commit to source control
↓
6. ✅ Deploy to other orgs (after creating Store in target org)
```
---
## 🚨 What NOT to Do
❌ **Don't create storefront metadata from scratch**
- The Commerce setup wizard generates hundreds of configuration values
- Manual creation will miss critical Store-to-Experience associations
❌ **Don't try to deploy storefront without Store**
- Deploying Experience metadata to an org without the Commerce Store will fail
- Commerce components require WebStore records to exist
❌ **Don't version control Commerce Store data**
- WebStore records, BuyerGroups, EntitlementPolicies are runtime data
- Cannot be captured as deployable metadata (use data export/import instead)
❌ **Don't skip the Commerce setup wizard**
- Even if you think you can do it faster manually
- The wizard creates essential relationships and default configurations
---
## 📋 Pre-Deployment Checklist for Other Orgs
When deploying your storefront to a new org:
- [ ] Target org has Commerce licenses (B2B Commerce or B2C 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
- [ ] Buyer users and Commerce Admin permissions are assigned
- [ ] Product catalog, price books, and inventory exist in target org
- [ ] Payment, tax, shipping providers configured
- [ ] Only then deploy the Experience metadata:
```bash
sf project deploy start --source-dir force-app/main/default/digitalExperiences/
```
---
## 🔗 Related Workflows
### For B2B Commerce:
- Create Buyer Accounts and Contacts
- Assign Accounts to Buyer Groups
- 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:
- Seed product catalog (Products, ProductCategory, ProductCatalog)
- Create price books and price book entries
- Configure inventory (ProductItem, LocationInventory)
- Set up search facets and filters
---
## 💡 Agent Guidance: What to Create vs What to Retrieve
**When user asks: "Create a B2B Commerce storefront"**
**Your response should be:**
1. ✅ Explain the Store vs Storefront distinction
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
**Acceptable to create from scratch:**
- Custom LWCs for storefront extensions (hero banners, promotions, custom product cards)
- Content pages that don't use Commerce components
- Utility components (navigation helpers, breadcrumbs)
**Must be retrieved from org:**
- Core storefront Experience metadata
- Commerce-managed pages (PLP, PDP, Cart, Checkout)
- Store configuration and routing
---
## 📚 Additional Resources
**Commerce Store Setup:**
- 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
- Help Article: "Customize Your Commerce Storefront"
- Developer Guide: "Build Custom Commerce Components"
**Metadata Retrieval:**
```bash
# List all retrievable metadata types
sf org list metadata --metadata-type DigitalExperience
sf org list metadata --metadata-type ExperienceBundle
# Retrieve specific experience
sf project retrieve start --metadata ExperienceBundle:YourStoreName
```
---
## 🎓 Key Takeaway
**Commerce is a TWO-STEP process:**
1. **Create Store** (in org, runtime data) → Generates default storefront
2. **Retrieve & Customize Storefront** (source control, metadata) → Extend with custom features
**Never skip step 1. Never manually create what step 1 generates.**