afv-library/rules/commerce/README.md

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

// 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

# 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:

# 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

# WRONG - WebStore is data, not metadata
sf project retrieve start --metadata WebStore
# Error: WebStore is not a valid metadata type

Correct:

# 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
• Commerce Setup Guide

Developer Guides:

• B2B Commerce Developer Guide
• Commerce APIs

Community:

• Commerce on Core Trailblazer Community