diff --git a/manifest.json b/manifest.json index 09efdbd..a1d945e 100644 --- a/manifest.json +++ b/manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-03-07T00:00:00.000Z", + "generatedAt": "2026-02-17T21:01:05.349Z", "branch": "main", "prompts": [ { @@ -52,24 +52,6 @@ "admin" ] }, - { - "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": [ - "b2b", - "scom", - "scom b2b", - "commerce b2b", - "storefront", - "lwr", - "retrieve", - "metadata" - ], - "requires_setup": true, - "setup_summary": "Requires Commerce licenses; agent guides through store creation interactively" - }, { "name": "Account Layout Field Enhancement", "path": "prompts/getting-started/add-fields-pagelayout.md", @@ -339,23 +321,6 @@ "security" ] }, - { - "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": [ - "b2b", - "scom", - "scom b2b", - "commerce b2b", - "store", - "storefront", - "lwr", - "experience-cloud", - "rules" - ] - }, { "name": "LWC Development Guardrails", "path": "rules/lwc-development/lwc-requirements.md", diff --git a/prompts/commerce/README.md b/prompts/commerce/README.md deleted file mode 100644 index e45136b..0000000 --- a/prompts/commerce/README.md +++ /dev/null @@ -1,189 +0,0 @@ -# Commerce Prompts - -Prompts for building and managing Salesforce B2B 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 - -> See full interactive flow in `create-retrieve-b2b-storefront.md` - -```bash -# 1. Create Commerce Store in org (via UI) -# Setup → Commerce → Stores → Create Store - -# 2. List available storefronts -sf org list metadata --metadata-type DigitalExperienceConfig - -# 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 - -# 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 from scratch. The Commerce setup wizard generates complex configurations that are difficult to replicate manually. - -## Available Prompts - -### 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 licenses available in org -- Experience Cloud enabled -- Salesforce CLI authorized with default org - -**What it does:** -- 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-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-b2b-store-requirements.md rule -2. Create Store in org via Commerce app -3. Use "Create and Retrieve B2B Commerce Storefront" 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/ -└── 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: -- `b2b` - B2B Commerce specific -- `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 -- `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/) -- [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) -- [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 DigitalExperienceConfig - -# Retrieve storefront -sf project retrieve start -m DigitalExperienceBundle:site/StoreName - -# Deploy storefront -sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/StoreName/ -``` diff --git a/prompts/commerce/create-retrieve-b2b-storefront.md b/prompts/commerce/create-retrieve-b2b-storefront.md deleted file mode 100644 index edb51a7..0000000 --- a/prompts/commerce/create-retrieve-b2b-storefront.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -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/ -``` - -**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 diff --git a/rules/commerce/README.md b/rules/commerce/README.md deleted file mode 100644 index f57b8f4..0000000 --- a/rules/commerce/README.md +++ /dev/null @@ -1,243 +0,0 @@ -# Commerce Rules - -Rules and guardrails for developing B2B 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 | - -> **See:** `commerce-b2b-store-requirements.md` for comprehensive details - -## Available Rules - -### Commerce B2B Store Creation Requirements -**`commerce-b2b-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:** -> See full workflow in `commerce-b2b-store-requirements.md` - -## When to Apply These Rules - -### Trigger: User asks to create Commerce storefront - -**User says:** -- "Create a B2B Commerce store" -- "Build a B2B storefront" -- "Set up Commerce on Core" -- "Create an LWR Commerce site" -- "Build a digital storefront" - -**Agent should:** -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 - -**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/digitalExperiences/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/digitalExperiences/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 org list metadata --metadata-type DigitalExperienceConfig -sf project retrieve start -m DigitalExperienceBundle:site/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, Commerce) - - Identify if request is for creation vs modification vs deployment - -2. **Rule Application** - - Load `commerce-b2b-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-b2b-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/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 - -## 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) diff --git a/rules/commerce/commerce-b2b-store-requirements.md b/rules/commerce/commerce-b2b-store-requirements.md deleted file mode 100644 index 86e4f66..0000000 --- a/rules/commerce/commerce-b2b-store-requirements.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -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 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) 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 - ---- - -## 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/` -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) - -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 - - Follow the store setup wizard - -3. **Store Setup Wizard will create:** - - WebStore record with unique name - - Default buyer group (associated with Accounts) - - 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 - - Account-based features - -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 org list metadata --metadata-type DigitalExperienceConfig - -# Retrieve the complete ExperienceBundle -# 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:** -``` -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) -- [ ] 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 - -### General Setup: -- 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 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" - -**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 DigitalExperienceConfig - -# Retrieve specific experience -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 - -**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.**