|
| 1 | +--- |
| 2 | +title: App submission guidelines for Adobe Commerce apps |
| 3 | +description: Learn how to submit your app for review and app requirements and best practices. |
| 4 | +keywords: |
| 5 | + - Extensibility |
| 6 | +--- |
| 7 | + |
| 8 | +import Webhook from '/src/_includes/webhook-auth.md' |
| 9 | + |
| 10 | +# App submission guidelines |
| 11 | + |
| 12 | +This page provides a list of requirements and best practices for Adobe Commerce app developers to ensure your app is ready for submission. Following these guidelines will help reduce rejection rates and improve the quality of your app. |
| 13 | + |
| 14 | +The Adobe Commerce App Builder review process evaluates submissions across multiple criteria including documentation quality, security practices, code structure, and functionality. |
| 15 | + |
| 16 | +<InlineAlert variant="info" slots="text"/> |
| 17 | + |
| 18 | +For more general information on the application submission process, refer to the [App Builder distribution documentation](https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/distribution). |
| 19 | + |
| 20 | +## Review process |
| 21 | + |
| 22 | +When you submit your Commerce App Builder extension, our review team will evaluate your submission against the criteria outlined on this page. |
| 23 | + |
| 24 | +- **[Requirements](#requirements)** - Critical requirements that must be addressed before approval |
| 25 | +- **[Best practices](#best-practices)** - Recommended improvements that enhance quality but don't block approval |
| 26 | + |
| 27 | +## If your app is rejected |
| 28 | + |
| 29 | +If your submission is rejected: |
| 30 | + |
| 31 | +1. Review the specific feedback provided by the review team. |
| 32 | +1. Address all requirements listed in the rejection notice. |
| 33 | +1. Consider implementing best practices to improve quality. |
| 34 | +1. Resubmit your updated extension. |
| 35 | + |
| 36 | +## Requirements |
| 37 | + |
| 38 | +The following requirements must be met for your app to be accepted. If your app does not meet these requirements, it will be rejected. |
| 39 | + |
| 40 | +### Documentation |
| 41 | + |
| 42 | +- Installation guide clarity |
| 43 | + - **Prerequisites**: Add clear prerequisites (example: Admin UI SDK must be enabled). |
| 44 | + - **Version requirements**: Indicate the required module versions (example: Admin UI SDK minimum version `3.0.0`). |
| 45 | + - **Developer documentation**: Include links to relevant Adobe developer documentation (example: App Builder [getting started guide](https://developer.adobe.com/app-builder/docs/get_started/)). |
| 46 | + - **Environment setup**: Provide a `.env.dist` file with all required environment variables, clearly labeled with guidance. |
| 47 | + - **PaaS support**: Documentation must include installation steps for PaaS merchants. This means if you are submitting an app for Adobe Commerce as a Cloud Service (SaaS), you also need to support Adobe Commerce on cloud infrastructure (PaaS) and Adobe Commerce on-premises (on-prem). |
| 48 | + |
| 49 | +- Security awareness |
| 50 | + - **Screenshot security**: Ensure no screenshots contain access tokens, secrets, or API keys. |
| 51 | + - **Sensitive data**: Do not expose credentials or sensitive information in the documentation. |
| 52 | + |
| 53 | +- `README` content quality |
| 54 | + - **Project-specific language**: Use project-specific language. Avoid generic references to "Adobe", "Magento" or "starter kit". |
| 55 | + - **Configuration details**: Clearly list the app configuration and any third-party service-specific setup steps. |
| 56 | + - **Usage instructions**: Add instructions on how to use the app post-installation. |
| 57 | + - **Professional writing**: Remove any placeholder content and fix any typos. |
| 58 | + |
| 59 | +### Security |
| 60 | + |
| 61 | +- Authentication and authorization |
| 62 | + - **Action security**: All runtime actions used by webhooks or admin apps must use `require-adobe-auth: true` in the action configuration. |
| 63 | + - This requires that PaaS apps use Admin UI SDK 3.0 or later. You can add the following to your `composer.json` file to avoid version restrictions: |
| 64 | + |
| 65 | + ```json |
| 66 | + "magento/commerce-backend-sdk": "3.0.0 as 2.0.0" |
| 67 | + ``` |
| 68 | + |
| 69 | + - **Webhook protection**: For webhooks, actions need to be protected by [signature verification](../webhooks/signature-verification.md) or by enabling the use of IMS authentication in your configuration file. |
| 70 | + |
| 71 | + <Webhook /> |
| 72 | + |
| 73 | +- Credential management |
| 74 | + - **Hardcoded secrets**: No hardcoded secrets (account IDs or tokens) in the code or configuration files. |
| 75 | + - **Encryption**: Secrets or credentials provided in runtime must be encrypted before persisting in state/files. |
| 76 | + - See [Best Practices for Credentials](https://developer.adobe.com/commerce/extensibility/app-development/best-practices/credentials/). |
| 77 | + - **No logging of secrets**: No logging of sensitive credentials or tokens in any runtime action. |
| 78 | + |
| 79 | +- Vulnerability assessment |
| 80 | + - **Security audit**: Run `npm audit` to ensure there are no `critical` or `high` vulnerabilities. |
| 81 | + - **Dependency check**: Review all dependencies for known security issues. |
| 82 | + |
| 83 | +### Project structure |
| 84 | + |
| 85 | +- Configuration files |
| 86 | + - **Environment variables**: Provide a clear `.env.dist` file containing all needed keys. Remove any unused keys. |
| 87 | + - **YAML configuration**: Review `deploy.yaml` and `app.config.yaml` for accurate app IDs, event configs, and scopes. |
| 88 | + - **Commerce product**: Define `commerce` as a required product in `app.config.yaml`. See [required products](https://developer.adobe.com/commerce/extensibility/app-development/required-products/) for more information. |
| 89 | + - **Package metadata**: Ensure `package.json` is updated with an app-specific `name`, `version`, and `author`. |
| 90 | + |
| 91 | +- Project cleanup |
| 92 | + - **Unused folders**: Remove any unused or unnecessary folders. |
| 93 | + - **Adobe compliance files**: Do not include any Adobe compliance files, such as `CODE_OF_CONDUCT` or `COPYRIGHT`, that you copied from a starter kit. |
| 94 | + - **Multi-environment support**: Provide out-of-the-box support for SaaS and PaaS deployments by using configuration or different initialization scripts. |
| 95 | + |
| 96 | +### Code review |
| 97 | + |
| 98 | +- Code quality |
| 99 | + - **`state` usage**: Avoid inappropriate use of `state`. For example, when log forwarding instead of using `state`, use more modern solutions such as App Builder's [log forwarding](https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/application_logging/logging#forwarding-application-logs) feature. |
| 100 | + - **Hardcoded values**: Look for hardcoded values that should be configurable |
| 101 | + |
| 102 | +- Commerce compatibility |
| 103 | + - **Multi-flavor support**: Ensure compatibility between commerce flavors (PaaS & SaaS): |
| 104 | + - ​<Edition name="saas" /> IMS Auth instead of OAuth1 |
| 105 | + - ​<Edition name="saas" /> Base URL with tenantId and without "rest" |
| 106 | + - **Action scoping**: All runtime actions must be scoped and documented, if they are exposed as webhooks. |
| 107 | + |
| 108 | +### Dependencies |
| 109 | + |
| 110 | +- Dependency management |
| 111 | + - **Unused dependencies**: Remove any unused dependencies reported by `npx npm-check`. |
| 112 | + - **Direct dependencies**: Ensure all direct dependencies are declared in `package.json`. |
| 113 | + - **Version updates**: Update major versions of critical packages. |
| 114 | + |
| 115 | +### Cleanup and quality assurance |
| 116 | + |
| 117 | +- Code cleanup |
| 118 | + - **Test suite**: Ensure tests all tests are passing. Run `npm test` to validate. |
| 119 | + |
| 120 | +### Configuration |
| 121 | + |
| 122 | +- Configuration best practices |
| 123 | + - **Input validation**: Ensure that all inputs in YAML files are defined as variables in the `.env.dist` file. |
| 124 | + - **Commerce product**: Define `commerce` as a required product in `app.config.yaml`. See [required products](https://developer.adobe.com/commerce/extensibility/app-development/required-products/) for more information. |
| 125 | + |
| 126 | +## Best practices |
| 127 | + |
| 128 | +The following best practices are not required for your app to be accepted, but they are recommended to improve the quality of your app and its integration with Adobe Commerce. |
| 129 | + |
| 130 | +### Project enhancement |
| 131 | + |
| 132 | +- Tracking and monitoring |
| 133 | + - **Starter kit info**: Include the [`starter-kit-info`](https://github.com/adobe/commerce-integration-starter-kit/blob/main/actions/starter-kit-info/index.js) runtime action for deployment tracking. |
| 134 | + - **Feature utilization**: Leverage new starter kit features where applicable. |
| 135 | + - [Integration starter kit](https://developer.adobe.com/commerce/extensibility/starter-kit/integration/) |
| 136 | + - [Checkout starter kit](https://developer.adobe.com/commerce/extensibility/starter-kit/checkout/) |
| 137 | + |
| 138 | +- Script management |
| 139 | + - **Script validation**: Execute everything in `package.json` scripts section and ensure there are no errors. |
| 140 | + - **Script cleanup**: Ensure there are no unused or non-working scripts. |
| 141 | + |
| 142 | +### Runtime and testing |
| 143 | + |
| 144 | +- Functional testing |
| 145 | + - **Deployment testing**: Deploy the project and conduct minimal functional testing. |
| 146 | + - **End-to-end validation**: Verify all major functionality works as documented. |
| 147 | + |
| 148 | +To facilitate proper testing during review, ensure you provide: |
| 149 | + |
| 150 | +- Clear installation and setup instructions |
| 151 | +- Required environment configurations |
| 152 | +- Test credentials or demo environments (if applicable) |
| 153 | +- Documentation of any third-party service dependencies |
| 154 | + |
| 155 | +### Cleanup and quality assurance |
| 156 | + |
| 157 | +- Code cleanup |
| 158 | + - **Development artifacts**: Remove `TODO` comments and unused scripts or handlers. |
| 159 | + - **Test scripts**: Add or remove test scripts in `package.json` based on actual test coverage. |
| 160 | + - **Development logs**: Remove unused development logs and console outputs. |
| 161 | + |
| 162 | +### Code review |
| 163 | + |
| 164 | +- Code quality |
| 165 | + - **Unused imports**: Remove any unused `imports` and validate with `npx npm-check`. |
| 166 | + - **Action consistency**: Ensure consistency and correctness in action names and routes. |
| 167 | + - **SDK migration**: Fully migrate Admin UI SDK 1.x extension points to 3.x if applicable. |
| 168 | + - **Hardcoded values**: Look for hardcoded values that should be configurable |
| 169 | + - **Duplicated logic**: Avoid duplicating SDK logic unnecessarily, such as OAuth or fetch wrappers. |
| 170 | + - **Action scoping**: All runtime actions must be scoped and documented, if they are exposed as webhooks. |
| 171 | + |
| 172 | +### Dependencies and maintenance |
| 173 | + |
| 174 | +- Version management |
| 175 | + - **Package updates**: Check for up-to-date package versions using `npx npm-check` (`MAJOR UP` label). |
| 176 | + - **Unused dependency check**: Check for unused dependencies using `npx npm-check` (`NOTUSED?` label). |
| 177 | + |
| 178 | +- Code optimization |
| 179 | + - **Handler cleanup**: Clean up any unused handlers or unused code, such as empty `preProcess` or `transformData` functions. |
| 180 | + - **Development cleanup**: Remove any unused logs that were during development. |
| 181 | + - **SDK logic**: Avoid duplicating SDK logic unnecessarily, such as OAuth or fetch wrappers. |
| 182 | + |
| 183 | +### Configuration |
| 184 | + |
| 185 | +- Configuration best practices |
| 186 | + - **Package-level inputs**: Use package-level inputs in YAML files instead of repeating environment variables. |
| 187 | + - **Environment variables**: Avoid structured data in environment variables, unless necessary. |
0 commit comments