Refer to the following guidelines to guarantee the quality and usability of your VTEX IO app during development.

Notice that you must respect these guidelines if you aim to publish your app at the VTEX App Store.

Use the VTEX IO infrastructure to build and deploy your extensions. The VTEX IO development platform uses cloud computing to ensure that your app runs without bottlenecks 24/7.

Efficiently utilizing APIs is paramount for optimal performance in your application. Whenever possible, leverage our pre-built VTEX IO Clients to harness the following advantages:

• Standardized code: VTEX IO Clients streamline interfacing with various services, providing standardized code across all applications.
• Automatic updates: VTEX consistently updates VTEX IO Clients, delivering new features, resolving bugs, and ensuring compatibility with the latest technologies.
• Simplified maintenance: By relying on VTEX IO Clients, you eliminate the need for extensive code maintenance.

Avoid unnecessary or excessive API calls and ensure they are fast and scalable. Excessive API calls can degrade your app's performance, increasing response times. Unnecessary API calls or lack of proper use of our Clients can lead to security issues. For more information, see our Clients documentation.

Performance of external systems

When you offer your app on the VTEX App Store, your app may become available to brands of all sizes across different time zones and business calendars. In this context, relying on a manual system with on-demand scalability can become a huge risk in terms of performance.

Builders work as an API responsible for configuring other IO services in your app. For developing and publishing apps for the VTEX App Store, the following builders must be up-to-date in your app's code:

• Node builder - version 6.x.
• React builder - version 3.x.
• Admin builder - version 1.x.
• Messages builder - version 1.x.
• Docs builder- version 0.x.
• Graphql builder -version 1.x.

When releasing a new version of your app, it's crucial to adhere to best practices. There are various types of versions to consider, including major, minor, and patch, as well as stable and beta releases. Select the appropriate version type based on the nature of the implemented changes. Special attention is required for breaking changes, which should always result in a new major version.

For more information, refer to the SemVer standard and our guide on Releasing a new app version.

To ensure that all points of contact between our retailers, their customers, and other parts of the ecosystem are protected and secure, we test if your app respects regulations on data traffic, usage, and storage worldwide.

Nevertheless, if you identify any security breaches after publishing your app, take the following measures:

1. Open a ticket requesting to remove your app from the VTEX App Store and avoid further installations of the unstable version.
2. Open a support ticket and notify us of the issue so that we can support retailers operating with this version and guide them on removing it from their stores.
3. Fix the security flaw and resubmit your application for homologation.

Once the new version is approved, the app will be available again in the VTEX App Store.

Having an appKey/appToken exposed in your code can cause serious security issues, like unwanted access. Instead of using a VTEX appKey/appToken pair, apps should use the existing tokens (ctx.authToken, ctx.vtex.storeUserAuthToken or ctx.vtex.adminUserAuthToken). For more information, see Connecting to VTEX Core Commerce APIs.

For user-initiated actions, apps should use either ctx.vtex.storeUserAuthToken or ctx.vtex.adminUserAuthToken (as opposed to ctx.authToken). For more information, see Connecting to VTEX Core Commerce APIs.

Outbound access policies (outbound-access) to VTEX resources should follow the principle of least privilege. In short, you only give access to what is really needed. For instance, the path should not be configured as *. See an example here of how it should be done.

As the name suggests, public routes do not require authentication when accessed from the frontend. Consequently, they should never reveal data sourced from private APIs, such as displaying a list of orders directly to the frontend. In this sense, a common mistake is failing to restrict routes intended exclusively for Admin usage. Additionally, keep in mind that GraphQL APIs are public by default, necessitating cautious schema design to avoid queries that inadvertently expose confidential information.

Access to REST APIs should be restricted using policies. Access to GraphQL APIs should be restricted using directives, either @auth or a custom-made one.

Single-tenant external systems should be used carefully. Data from one tenant must always be isolated from data from another tenant to prevent leakage and unwanted access. The isolation method will depend on the external system. One possible solution is to use the name (or other identifier) of the tenant in routes or as a parameter for access control or to define how the data is managed.

If using Master Data or VBase to store Personal Identifiable Information (PII), a mechanism must be in place to ensure compliance with the Right to be Forgotten or other similar data-protection practices. Possible solutions are to provide an option or endpoint in the app that erases the data, for instance, by using a delete operation with our Clients (Master Data, VBase) or through the API (Master Data v1, Master Data v2).

We should ensure that all PII being shared externally is strictly necessary for the app to work. If you have any questions, reach out to us via ticket.

Ensure that all messages are internationalized using the messages builder. Also, i18n keys should start with the domain (store/ for storefront and admin/ for Admin) where they are used. Otherwise, they will not render properly. For more information, see our reference for translating components.

When declaring routes, generic paths (e.g., /_v/orders/, /_v/settings) should be avoided to reduce chances of collision with other apps.

To mitigate this risk, consider adopting a naming convention that includes a distinctive prefix, typically the name of your app, when defining routes. This simple practice effectively reduces the chances of conflicts and ensures that your app's routes remain uniquely identifiable and isolated from others.

Our primary recommendation for defining the Admin settings form of your app is to leverage the settingsSchema structure, as it caters to the majority of use cases effectively.

However, for more specific cases where the schema is insufficient, you can create your form as a page of an Admin app. In such cases, our team will evaluate your requirements during the homologation process.

For homologation approval, your app must be plug-and-play. Those interested in your app should:

• Be able to install and configure it using only the VTEX Admin panel.
• Not considered external assistance to support the app implementation process.

Every app in the VTEX App Store must:

• Provide a direct support channel for retailers who install it, such as email, phone, ticketing tool, or a combination of these options.
• Have the first response time up to eight business hours in the developer's time zone. This requirement aims to ensure that store operations will not be affected by errors in third-party applications.

While developing your app and preparing the app for distribution, make sure to provide official documentation that supports future users in implementing and understanding your app.

The app documentation should include:

• Technical and commercial requirements for the app's operation.
• Installation and configuration guides.
• Answers to frequently asked questions.

For more information on the best practices for creating documentation, refer to Documentation guidelines.