{"id":50776320,"url":"https://github.com/salesforcecommercecloud/commerce-apps","last_synced_at":"2026-06-12T00:01:35.098Z","repository":{"id":350076616,"uuid":"1180888919","full_name":"SalesforceCommerceCloud/commerce-apps","owner":"SalesforceCommerceCloud","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-26T17:01:17.000Z","size":351,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T22:30:43.864Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go Template","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SalesforceCommerceCloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-13T14:18:28.000Z","updated_at":"2026-05-26T17:01:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SalesforceCommerceCloud/commerce-apps","commit_stats":null,"previous_names":["salesforcecommercecloud/commerce-apps"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/SalesforceCommerceCloud/commerce-apps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SalesforceCommerceCloud%2Fcommerce-apps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SalesforceCommerceCloud%2Fcommerce-apps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SalesforceCommerceCloud%2Fcommerce-apps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SalesforceCommerceCloud%2Fcommerce-apps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SalesforceCommerceCloud","download_url":"https://codeload.github.com/SalesforceCommerceCloud/commerce-apps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SalesforceCommerceCloud%2Fcommerce-apps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34222709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T00:01:30.859Z","updated_at":"2026-06-12T00:01:35.088Z","avatar_url":"https://github.com/SalesforceCommerceCloud.png","language":"Go Template","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eCommerce Apps\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eSalesforce Commerce Cloud\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  Build, package, and distribute installable extensions for Salesforce Commerce Cloud storefronts.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#published-apps\"\u003ePublished Apps\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e •\n  \u003ca href=\"#disclaimer\"\u003eDisclaimer\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What Are Commerce Apps?\n\nCommerce Apps are packaged extensions that add capabilities to [Storefront Next](https://developer.salesforce.com/docs/commerce/b2c-commerce) storefronts. A single app can bundle frontend UI components, backend API adapters, platform configuration, and merchant setup guidance into one installable unit called a **Commerce App Package (CAP)**.\n\nMerchants install Commerce Apps through Business Manager with a click-to-install experience. Developers build them here.\n\n**Three ways to build:**\n\n| Path | You Build | Platform Provides | Example |\n|------|-----------|-------------------|---------|\n| **UI Target Only** | React components for storefront extension points | Build-time injection via Vite plugin | Ratings widget, store locator, loyalty badge |\n| **API Adapter Only** | Script API hooks implementing platform contracts | Hook dispatch, lifecycle management | Tax calculation (Avalara), fraud detection |\n| **Full App** | Both UI components and backend adapters | All of the above | Shipping estimator, BNPL provider |\n\n## Quick Start\n\n### Using Agent Skills\n\nIf you're using Claude Code, Cursor, Copilot, or another IDE with plugin support, install the `cap-dev` plugin for skills that streamline the full development workflow — see [Agent Skills](#agent-skills) below.\n\n### Manual Development\n\nBuild your app directory with the following CAP structure:\n\n```\ncommerce-{app-name}-app-v{version}/\n├── commerce-app.json                # App metadata\n├── README.md                        # Documentation\n├── app-configuration/\n│   ├── tasksList.json              # Post-install merchant setup steps\n│   └── adminComponents.json        # Optional: BM admin UI components (e.g., storefrontComponentVisibility)\n├── icons/                          # App icon (required)\n│   └── {icon-filename}.png         # CI extracts to commerce-apps-manifest/icons/\n├── cartridges/                     # Backend-only or Fullstack apps\n│   ├── site_cartridges/{name}/    # Script API hook implementations\n│   │   ├── package.json\n│   │   ├── cartridge/scripts/\n│   │   │   ├── hooks.json         # Registers hooks with the platform\n│   │   │   ├── hooks/             # Hook implementations\n│   │   │   ├── helpers/           # Business logic\n│   │   │   └── services/          # Service framework wrappers\n│   │   └── test/                  # Unit tests\n│   └── bm_cartridges/             # Business Manager extensions (optional)\n├── storefront-next/src/extensions/{name}/  # UI-only or Fullstack apps\n│   ├── target-config.json         # Maps components → storefront extension points\n│   ├── index.ts                   # Barrel exports\n│   ├── components/\n│   └── locales/                   # Required: en-US, en-GB, it-IT\n│       ├── en-US/translations.json\n│       ├── en-GB/translations.json\n│       └── it-IT/translations.json\n├── impex/                          # Backend-only or Fullstack apps\n│   ├── install/                   # Service configs, custom attributes, preferences\n│   │   ├── services.xml\n│   │   ├── meta/\n│   │   │   ├── system-objecttype-extensions.xml\n│   │   │   └── custom-objecttype-definitions.xml\n│   │   └── sites/SITEID/\n│   │       └── preferences.xml\n│   └── uninstall/                 # Cleanup for uninstalled apps\n│       └── services.xml\n```\n\n**Three architectures:**\n- **UI-only**: Has `storefront-next/`, no `cartridges/` or `impex/`\n- **Backend-only**: Has `cartridges/` and `impex/`, no `storefront-next/`\n- **Fullstack**: Has all three: `storefront-next/`, `cartridges/`, and `impex/`\n\n### `app-configuration/adminComponents.json` (optional)\n\nDeclares Business Manager admin UI components that the merchant sees after installing the app. The file is a JSON object with a `configuration` array of interactive setting entries. Every entry must be an object with a non-empty string `type`. Other fields like `header` and `description` are free-form and not validated.\n\nThe currently supported component type is **`storefrontComponentVisibility`**, which renders one boolean toggle per UI target the app registers, letting the merchant turn each target on or off without touching code. Toggling a target opens a PR against the merchant's Storefront Next repo to update `target-config.json`. When `type` is `storefrontComponentVisibility`, `attributes[]` is required:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `id` | string | Yes | The `sfcc.*` UI target ID this toggle controls. Must match a target the app registers in `storefront-next/src/extensions/{appName}/target-config.json`. |\n| `label` | string | Yes | Label shown next to the toggle in BM. |\n| `defaultValue` | boolean | Yes | Whether the surface area is enabled by default on install. |\n\nExample:\n\n```json\n{\n  \"configuration\": [\n    {\n      \"type\": \"storefrontComponentVisibility\",\n      \"header\": \"Component Visibility\",\n      \"description\": \"Control where the component appears on the storefront.\",\n      \"attributes\": [\n        { \"id\": \"sfcc.checkout.shippingAddress.after\", \"label\": \"Show on Checkout\", \"defaultValue\": true },\n        { \"id\": \"sfcc.orderSummary.adjustments\",       \"label\": \"Show on Order Summary\", \"defaultValue\": false }\n      ]\n    }\n  ]\n}\n```\n\nCI validates this file's shape on PR. If the file is omitted, the merchant doesn't see a visibility section in BM and every registered target stays enabled.\n\n## Published Apps\n\nApps are organized by domain and app name:\n\n```\n{domain}/{appName}/\n  ├── {appName}-v{version}.zip     # The installable CAP\n  └── catalog.json                  # Version history (updated by CI)\n\ncommerce-apps-manifest/\n  ├── manifest.json                 # Root manifest with all app entries\n  ├── icons/\n  │   └── {iconName}.png            # App icons\n  └── translations/\n      ├── en-US.json                # App translations (minimum)\n      ├── de.json\n      ├── fr.json\n      └── ... (13 locale files)\n```\n\n**Example structure:**\n\n```\ntax/\n├── avalara-tax/\n│   ├── avalara-tax-v0.2.8.zip\n│   └── catalog.json\n└── vertex-tax/\n    ├── vertex-tax-v1.0.0.zip\n    └── catalog.json\n\npayment/\n├── stripe-payment/\n│   ├── stripe-payment-v1.0.0.zip\n│   └── catalog.json\n└── adyen-payment/\n    ├── adyen-payment-v1.0.0.zip\n    └── catalog.json\n\ncommerce-apps-manifest/\n├── manifest.json              # Contains all app entries\n├── icons/\n│   ├── avalara.png\n│   ├── stripe.png\n│   └── bazaarvoice.png\n└── translations/\n    ├── en-US.json            # All app translations\n    ├── de.json\n    └── ... (13 locale files)\n```\n\n**Note:** Extracted app directories (`commerce-{app-name}-app-v{version}/`) are for development only and should NOT be committed to the repository.\n\n### Domains\n\nEvery app's `domain` field must be one of these. Domains use hyphen-case. Provider domains (`tax`, `payment`, `shipping`) show under \"Providers\" on the checkout hub; all other domains show under \"Additional Setup\".\n\n| Domain | Section | Description | Example Apps |\n|--------|---------|-------------|--------------|\n| `tax` | Providers | Tax calculation and compliance | Avalara, Vertex |\n| `payment` | Providers | Payment processing | Stripe, Adyen, PayPal |\n| `shipping` | Providers | Shipping and fulfillment | ShipStation, EasyPost |\n| `gift-cards` | Additional Setup | Gift card purchasing, redemption, and balance | Salesforce Gift Cards, Adyen Gift Cards |\n| `ratings-and-reviews` | Additional Setup | Product ratings and reviews | Bazaarvoice, Yotpo, PowerReviews |\n| `loyalty` | Additional Setup | Loyalty programs and rewards | LoyaltyLion, Smile.io |\n| `search` | Additional Setup | Search and merchandising | Algolia, Elasticsearch |\n| `address-verification` | Additional Setup | Address validation and standardization | Smarty, Google Address Validation |\n| `analytics` | Additional Setup | Analytics and reporting | Google Analytics, Segment |\n| `approaching-discounts` | Additional Setup | Approaching discount notifications | Salesforce Approaching Discounts |\n| `fraud` | Additional Setup | Fraud detection and prevention | Signifyd, Forter, Riskified |\n\n## Tech Stack\n\nCommerce App frontend extensions target the Storefront Next stack:\n\n| Layer | Technology |\n|-------|-----------|\n| Framework | React 19 |\n| Language | TypeScript (strict) |\n| Build | Vite |\n| Styling | Tailwind CSS 4 (`@theme inline`, no config file) |\n| Components | ShadCN UI (29 primitives on Radix UI) |\n| Variants | CVA (class-variance-authority) |\n| Routing | React Router 7 |\n| i18n | react-i18next |\n| Component docs | Storybook 10 |\n| Unit testing | Vitest + React Testing Library |\n| E2E testing | CodeceptJS + Playwright |\n\nBackend adapters use the Commerce Cloud Script API (CommonJS, `require('dw/...')` modules).\n\n## Agent Skills\n\nTurn your coding agent into a Commerce Apps specialist. Skills give Claude Code, Cursor, GitHub Copilot, and Codex deep expertise in scaffolding, packaging, validating, and submitting Commerce App Packages.\n\nSkills follow the open [Agent Skills](https://agentskills.io/home) standard and work with [Claude Code](https://claude.ai/code), Cursor, GitHub Copilot, VS Code, Codex, and others.\n\n\u003e [!TIP]\n\u003e For B2C Commerce development and operations skills, also install the **B2C Developer Tooling** plugins. See the [B2C DX documentation](https://salesforcecommercecloud.github.io/b2c-developer-tooling/) for installation instructions.\n\n### Quick Start\n\nInstall via your IDE's plugin marketplace or manually copy skills into your IDE's skills directory.\n\n#### Claude Code\n\n```bash\nclaude plugin marketplace add SalesforceCommerceCloud/commerce-apps\nclaude plugin install cap-dev --scope project\n```\n\nUse `--scope user` instead to install globally across all projects.\n\n#### GitHub Copilot (VS Code)\n\nIn VS Code, open the Command Palette (`Cmd/Ctrl+Shift+P`) and run:\n\n```\nChat: Install Plugin from Source\n```\n\nThen enter: `SalesforceCommerceCloud/commerce-apps`\n\n#### GitHub Copilot CLI\n\n```bash\ncopilot plugin marketplace add SalesforceCommerceCloud/commerce-apps\ncopilot plugin install cap-dev@commerce-apps\n```\n\n#### Codex\n\n```bash\ncodex plugin marketplace add SalesforceCommerceCloud/commerce-apps\n```\n\nThen in Codex, run `/plugins`, select the \"Commerce Apps\" marketplace, and install the `cap-dev` plugin.\n\n#### B2C CLI\n\nThe [B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/) can install skills to any supported IDE:\n\n```bash\n# Interactive — choose skillset, IDE, and skills\nnpx @salesforce/b2c-cli setup skills\n\n# Non-interactive — install to a specific IDE\nnpx @salesforce/b2c-cli setup skills cap-dev --ide cursor\n\n# Install globally (user scope)\nnpx @salesforce/b2c-cli setup skills cap-dev --ide cursor --global\n```\n\n#### Manual Installation\n\nFor IDEs without marketplace support, copy the skills directory:\n\n| IDE | Project Path | User Path |\n|-----|--------------|-----------|\n| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |\n| Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |\n| Codex | `.codex/skills/` | `~/.config/codex/skills/` |\n| OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |\n\nCopy the skills from this repository's `.claude/skills/` directory into the appropriate path for your IDE.\n\n### Available Skills\n\n| Skill | Description |\n|-------|-------------|\n| `scaffold-app` | Generate complete app structure (UI-only, Backend-only, or Fullstack) |\n| `package-app` | Package app into registry-ready ZIP (handles new apps and version bumps) |\n| `generate-service-impex` | Generate service credentials, profiles, and definitions |\n| `generate-site-preferences-impex` | Generate custom site preference configurations |\n| `generate-custom-object-impex` | Generate custom object type definitions |\n| `validate-impex` | Validate impex XML syntax, structure, and common errors |\n| `validate-app` | Comprehensive pre-submission validation (structure, manifest, SHA256, impex) |\n| `submit-app` | Guided PR submission with automated GitHub CLI integration |\n\n### Usage\n\nOnce installed, skills are available as slash commands in your IDE:\n\n```\n/scaffold-app        → Start a new Commerce App\n/package-app         → Package for submission\n/validate-app        → Run full validation suite\n/submit-app          → Submit PR to registry\n```\n\nOr ask your agent naturally:\n\n```\n\"Create a new tax app called my-tax\"\n\"Package the my-tax app for submission\"\n\"Validate my app before I submit\"\n\"Generate service impex for a REST API integration\"\n```\n\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for complete submission requirements.\n\n### Publishing Workflow\n\n**Using Agent Skills (Recommended):**\n\n1. **Scaffold new app:** `/scaffold-app`\n2. **Build your app code** (cartridges, extensions, etc.)\n3. **Generate impex:** `/generate-service-impex`, `/generate-site-preferences-impex`\n4. **Package app:** `/package-app`\n5. **Validate:** `/validate-app`\n6. **Submit PR:** `/submit-app`\n\n**Manual Process:**\n\n1. Build your app directory with required structure\n2. Package as a CAP ZIP file: `zip -r my-app-v1.0.0.zip commerce-my-app-app-v1.0.0/ -x \"*.DS_Store\" -x \"__MACOSX/*\" -x \"*/.*\"`\n3. Generate SHA256 hash: `shasum -a 256 my-app-v1.0.0.zip`\n4. Update root manifest at `commerce-apps-manifest/manifest.json` with app entry (id, name, description, iconName, domain, version, zip, sha256)\n5. Add translations to `commerce-apps-manifest/translations/en-US.json` (minimum requirement)\n6. Create `catalog.json` with INIT placeholder (new apps only)\n7. Place ZIP at `{domain}/{appName}/` where `{appName}` matches the \"id\" field (e.g., `tax/avalara-tax/` or `address-verification/loqate-address-verification/`)\n9. Delete old ZIP versions: `rm -f {app-name}-v*.zip` (keep only the latest version)\n10. Commit ONLY the ZIP, root manifest, icon, translations, and catalog.json (do NOT commit extracted directories)\n11. Open a PR\n\n**CI Validation:** Validates ZIP structure, manifest format, and SHA256 hash. On merge, creates a Git tag, extracts app icons to `commerce-apps-manifest/icons/`, and updates the catalog automatically.\n\n**Updating an app:** Update the ZIP, root manifest entry, and icon/translations (if changed). Do NOT add new versions to `catalog.json` (CI handles it). You may add `\"deprecated\": true` to existing versions if needed.\n\n### What to Commit\n\nOnly commit these files to the repository:\n\n✅ **DO commit:**\n- `{domain}/{appName}/{appName}-v{version}.zip` - The packaged app\n- `commerce-apps-manifest/manifest.json` - Root manifest with app entry\n- `commerce-apps-manifest/translations/en-US.json` - App translations (minimum)\n- `{domain}/{appName}/catalog.json` - Version catalog (new apps only, with INIT values)\n\n**Note:** App icons are automatically extracted from the ZIP by the CI workflow and added to `commerce-apps-manifest/icons/` - do NOT manually commit icons.\n\n❌ **DO NOT commit:**\n- `commerce-{app-name}-app-v{version}/` - Extracted app directories (dev only)\n- `.DS_Store`, `Thumbs.db` - System files\n- `node_modules/` - Dependencies\n- Old ZIP versions - Delete before committing\n- IDE files (`.vscode/`, `.idea/`)\n\nThe repository `.gitignore` is configured to exclude extracted directories and system files.\n\n### External Contributors\n\nAll external contributors must sign the Contributor License Agreement (CLA). A prompt to sign the agreement appears when a pull request is submitted.\n\n## Disclaimer\n\nThis repository may contain forward-looking statements that involve risks, uncertainties, and assumptions. If any such risks or uncertainties materialize or if any of the assumptions prove incorrect, results could differ materially from those expressed or implied. For more information, see [Salesforce SEC filings](https://investor.salesforce.com/financials/).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u0026copy; Copyright 2026 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners.\u003cbr\u003e\n  Built for ISV developers by the Commerce Apps team at Salesforce Commerce Cloud.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalesforcecommercecloud%2Fcommerce-apps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsalesforcecommercecloud%2Fcommerce-apps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalesforcecommercecloud%2Fcommerce-apps/lists"}