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.** diff --git a/skills/creating-b2b-commerce-store/SKILL.md b/skills/creating-b2b-commerce-store/SKILL.md new file mode 100644 index 0000000..f906c63 --- /dev/null +++ b/skills/creating-b2b-commerce-store/SKILL.md @@ -0,0 +1,169 @@ +--- +name: creating-b2b-commerce-store +description: "Interactive workflow to create Commerce B2B Stores and retrieve storefront metadata. Use when users want to: create B2B Commerce stores, build Commerce storefronts, set up B2B stores from Vibes, retrieve Commerce metadata, deploy Commerce experiences, work with DigitalExperienceBundle for Commerce." +Critical: "Agents must follow the interactive flow and NEVER create storefront metadata from scratch." +license: Apache-2.0 +compatibility: "Requires Commerce licenses, Experience Cloud, Salesforce CLI" +metadata: + version: "1.0" + category: "commerce" +--- + +# Commerce B2B Storefront Creation + +Interactive workflow to create a Commerce B2B Store in Salesforce and retrieve the auto-generated storefront metadata to your repository. + +## Critical Concepts + +Commerce B2B = Store (backend data) + Storefront (frontend metadata). **Store must be created first** in the org to auto-generate the Storefront. Never create storefront metadata manually. + +> See [Store vs Storefront Reference](references/store-vs-storefront.md) + +## When to Use This Skill + +Trigger when users request: +- "Create a B2B Commerce store" +- "Build a Commerce storefront" +- "Set up Commerce B2B" +- "Create B2B Commerce" +- "Retrieve Commerce storefront metadata" +- "Deploy B2B storefront" + +## Rules That Always Apply + +1. **Always follow the interactive flow.** Do NOT skip steps. Each step requires user confirmation before proceeding. + +2. **Never create storefront metadata manually.** The Commerce setup wizard generates hundreds of configuration values. Manual creation will fail. + +3. **Always list sites before retrieval.** Store names get underscores and number suffixes (e.g., "My B2B Store" → "My_B2B_Store1"). Let the user select from the actual list. + +4. **Always use `--json` flag.** Include `--json` on all Salesforce CLI commands for parseable output. + +## Interactive Workflow: 7 Steps + +### Step 1: Explain Commerce B2B Concept + +**Agent explains:** Commerce has Store (data) + Storefront (metadata). Store must be created first. + +> See: [Store vs Storefront Reference](references/store-vs-storefront.md) + +--- + +### Step 2: Guide User to Create B2B Store + +**Agent provides these steps:** + +1. Navigate to **Setup → Commerce → Stores** + - Or: **App Launcher → Commerce → Create Store** + +2. Click **"Create Store"** or **"Setup New Store"** + +3. Select **"Commerce Store"** as the store type + +4. Follow the wizard: + - **Store Name**: Choose descriptive name (e.g., "My B2B Store") + - Important: Spaces become underscores in folder names + - **Site URL**: Unique URL name for the site + +5. Complete wizard - it creates: + - WebStore record + - Default buyer group and entitlement policies + - Associated Digital Experience (LWR site) + +6. Optional: Configure payment gateway, tax provider, shipping + +**Agent then asks:** +"Have you completed creating the B2B Store in your org? Reply 'yes' when ready and provide the store name you used." + +--- + +### Step 3: Get User Confirmation + +**Agent waits for:** User confirmation and store name + +**Agent validates:** Store name format (no special characters, spaces will appear as underscores) + +**Agent acknowledges:** "Great! Let me list the available storefronts in your org..." + +--- + +### Step 4: List Available LWR Sites + +**Agent executes:** +```bash +sf org list metadata --metadata-type DigitalExperienceConfig --json +``` + +**Agent should:** +- Parse JSON output to extract site names +- Display as numbered list +- Explain naming (underscores, number suffixes) + +**Example output:** +``` +Available Digital Experience sites: +1. My_B2B_Store1 +2. Partner_Portal +3. Customer_Community +``` + +--- + +### Step 5: Let User Select Storefront + +**Agent asks:** +"Which site corresponds to your B2B Store? Select the site name:" + +**Agent validates:** Selection matches available sites + +**Agent confirms:** "Got it! I'll retrieve metadata for [site-name]..." + +--- + +### Step 6: Retrieve Storefront Metadata + +**Agent executes:** +```bash +sf project retrieve start -m DigitalExperienceBundle:site/ --json +``` + +**Agent should:** +- Show retrieval progress +- Confirm successful retrieval +- List 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: Provide Next Steps + +**Agent provides:** + +✅ **Metadata retrieved successfully!** + +**Next steps:** +- Customize with custom LWCs or branding changes +- Deploy: `sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/My_B2B_Store1/ --json` + +**Resources:** [DigitalExperienceBundle Docs](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm), [B2B Commerce Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/) + +--- + +## Reference + +- **[store-vs-storefront.md](references/store-vs-storefront.md)** - Technical details on Store vs Storefront, source control, and why manual creation fails + +--- + +## Remember + +**Store first (creates storefront) → Retrieve → Customize** diff --git a/skills/creating-b2b-commerce-store/references/store-vs-storefront.md b/skills/creating-b2b-commerce-store/references/store-vs-storefront.md new file mode 100644 index 0000000..c396cab --- /dev/null +++ b/skills/creating-b2b-commerce-store/references/store-vs-storefront.md @@ -0,0 +1,169 @@ +# Commerce Store vs Storefront: Technical Reference + +## Overview + +Understanding the distinction between Commerce Store and Storefront is critical for successful Commerce B2B development. This document provides technical details about these two components and explains why they must be created in a specific order. + +--- + +## The Two Components + +### 1. Commerce Store (Backend Data) + +**What it is:** +- Runtime data and configuration created in the Salesforce org +- NOT source-controllable metadata +- Created through Commerce app UI + +**What it includes:** +- Store configuration and settings +- Default buyer groups (associated with Accounts) +- Entitlement policies (who can see which products) +- Pricing policies and price book mappings +- Payment gateway configuration (Stripe, Adyen, etc.) +- Tax provider configuration (Avalara, Vertex, manual) +- Shipping methods and configurations +- Product catalog associations +- Inventory locations +- Search index configurations + +**Where it lives:** +- Data records in standard Commerce objects: + - `WebStore` - Store settings and configuration + - `BuyerGroup` - Account-based buyer segments + - `EntitlementPolicy` - Product visibility rules + - `CommerceEntitlementProduct` - Product-policy associations + - `ProductCatalog` - Catalog definitions + - `Pricebook2` - Price books + - Additional payment, tax, shipping records + +**How to create:** +- Via UI: Setup → Commerce → Stores +- Cannot be created via Metadata API +- Cannot be deployed via `sf project deploy` + +--- + +### 2. Storefront (Frontend Metadata) + +**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 + +**What it includes:** +- ExperienceBundle metadata (`StorefrontName.digitalExperience-meta.xml`) +- URL routing configuration (`sfdc_cms__route`) +- Page definitions (`sfdc_cms__view`) + - Homepage + - Product List Pages (PLP) + - Product Detail Pages (PDP) + - Shopping cart + - Checkout flow + - Order confirmation + - Search results +- Lightning Web Components (product cards, cart components, checkout) +- Branding and theme configuration (`sfdc_cms__brandingSet`, `sfdc_cms__theme`) +- Page layouts (`sfdc_cms__themeLayout`) +- Navigation structure +- Custom LWCs for extensions + +**Where it lives:** +- `force-app/main/default/digitalExperiences/site/StorefrontName/` +- Example: `force-app/main/default/digitalExperiences/site/My_B2B_Store1/` + +**How to create:** +- Automatically generated by Commerce Store setup wizard +- Retrieved from org using Salesforce CLI +- Cannot be manually created from scratch + +**How to deploy:** +- Retrievable: `sf project retrieve start -m DigitalExperienceBundle:site/` +- Deployable: `sf project deploy start -m DigitalExperienceBundle` +- Source-controllable in Git + +--- + +## Why You Cannot Create Storefront Metadata from Scratch + +### Technical Reasons + +1. **Complex Dependency Chain** + - Create merchandisers store + - Create DigitalExperienceBundle + - Integrate both together + +2. **Hundreds of Auto-Generated Configurations** + - Component IDs and region IDs (UUIDs) + - WebStore associations + - Commerce-managed component configurations + - Default routing rules + - Search configurations + - Cart and checkout flow definitions + - Payment integration settings + +3. **Commerce-Managed Components** + - Product List Page (PLP) components + - Product Detail Page (PDP) components + - Cart components + - Checkout components + - Search components + - These require specific configurations from Store data + +4. **Metadata API Limitation** + - Metadata API deploys metadata types (Apex, LWCs, objects) + - Metadata API CANNOT create SObject data (WebStore records) + - Store creation requires data operations, not metadata operations + +--- + +## The Required Creation Order + +### Step 1: Create Commerce Store (Must Be First) + +``` +User Interface (Commerce App) + ↓ +WebStore Record Created + ↓ +BuyerGroup Records Created + ↓ +EntitlementPolicy Records Created + ↓ +Digital Experience Auto-Generated + ↓ +Commerce Components Configured +``` + +**Why this must be first:** +- Generates WebStore record with unique ID +- Creates default configurations +- Auto-generates associated Digital Experience +- Configures Commerce component relationships +- Sets up default buyer access rules + +### Step 2: Retrieve Storefront Metadata + +``` +sf org list metadata --metadata-type DigitalExperienceConfig + ↓ +Select Store from List + ↓ +sf project retrieve start -m DigitalExperienceBundle:site/ + ↓ +Metadata Saved to Local Repository + ↓ +Now Editable and Source-Controllable +``` + +--- + +## Key Takeaway + +**Commerce B2B = Store (data) + Storefront (metadata)** + +1. Create Store → generates Storefront +2. Retrieve Storefront → customize and version control if needed +3. Deploy Storefront → only after creating Store in target org + +**Never skip the Store creation. Never create Storefront metadata from scratch.**