From 3c36149e62f943f342a71db12511fade02d650cc Mon Sep 17 00:00:00 2001 From: nkurapati Date: Sun, 8 Mar 2026 00:52:06 +0530 Subject: [PATCH] Add instructions to create commerce b2b store from vibes --- manifest.json | 35 +- prompts/commerce/README.md | 185 +++++++++ .../commerce/retrieve-commerce-storefront.md | 356 ++++++++++++++++++ rules/commerce/README.md | 250 ++++++++++++ rules/commerce/commerce-store-requirements.md | 309 +++++++++++++++ 5 files changed, 1134 insertions(+), 1 deletion(-) create mode 100644 prompts/commerce/README.md create mode 100644 prompts/commerce/retrieve-commerce-storefront.md create mode 100644 rules/commerce/README.md create mode 100644 rules/commerce/commerce-store-requirements.md diff --git a/manifest.json b/manifest.json index a1d945e..920bb76 100644 --- a/manifest.json +++ b/manifest.json @@ -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", diff --git a/prompts/commerce/README.md b/prompts/commerce/README.md new file mode 100644 index 0000000..975818d --- /dev/null +++ b/prompts/commerce/README.md @@ -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/ +``` diff --git a/prompts/commerce/retrieve-commerce-storefront.md b/prompts/commerce/retrieve-commerce-storefront.md new file mode 100644 index 0000000..6372d2a --- /dev/null +++ b/prompts/commerce/retrieve-commerce-storefront.md @@ -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 + + + + ... + +``` + +### 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: +# true +# +# lightningCommunity__Page +# +``` + +**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) diff --git a/rules/commerce/README.md b/rules/commerce/README.md new file mode 100644 index 0000000..ea7169d --- /dev/null +++ b/rules/commerce/README.md @@ -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) diff --git a/rules/commerce/commerce-store-requirements.md b/rules/commerce/commerce-store-requirements.md new file mode 100644 index 0000000..9ac56b1 --- /dev/null +++ b/rules/commerce/commerce-store-requirements.md @@ -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.**