- VTEX IO external developers
- Basic knowledge of how IO apps are structured
Disclaimer: These are not guidelines for apps' implementations!
So, you're starting to develop a VTEX IO app and, as our development flow describes, you first need to request permission to link and eventually publish your app. You need to inform its name, vendor, major and also what's the motivation for developing such app. How should you better fill this information?
To avoid receiving a "request denied" from our whitelist team, we're here to clarify our app naming. Follow it, and you'll have a better chance to have your app's permission granted!
We often receive requests from partners developing one single functionality, but for multiple apps. For example, let's suppose you're developing an integration with Instagram(with vendor you) and you eventually need to have an admin session, a backend service and a storefront page. You may be inclined to request whitelist for the apps:
you.store-instagramfor exporting store blocks.you.admin-instagramfor creating an session on admin.you.instagram-graphqlfor the backend service.
But, there's no need for that 🚫. We at VTEX usually take this approach because our apps are used by multiple modules, but it's better to keep functionality together. Thanks to our builder platform, you can package all of those use cases into one single app: you.instagram ✅
It's even easier for other stores to install your app, since they'll only need one single command vtex install you.instagram, and not manage to install dependencies in order.
❗ Keep in mind to not abuse of this guideline and keep many functionalities into one generic app!
Beware that the app name you fill on the whitelist form will be the one you'll use on development, on the manifest.json file. You should fill it correctly!
Apps' names are kebab-case, or, basically, just lowercase letters separated with hyphens. They should also not contain special characters (like ., *, @...) or start with numbers (although they may have it elsewhere).
And, of course, they should concisely express the app's purpose. You should not call our Instagram example app integration, social-media or in! Also, theme apps should only use the store builder!
integrationInstagram Integrationi2plus2insta%gram
instagram-integrationinstagramstore-name-themeservice-b2b
For those who're interested, the validation regex for app's name is:
[a-z][a-z0-9-]{0,126}[a-z0-9]
We follow the Semantic Versioning specification for versioning our apps, which differences how we release new version. For development, you should always start with major 0, so, for new apps, don't request whitelist for majors 1 or greater.
When publishing the app, making it publicaly available, it should start with major 1, like 1.0.0.
If you want to know more about VTEX versioning and release process, check this doc on our VTEX IO documentation.
The vendor field on an app represents its owner, usually who is developing the application. It always maps for a VTEX account. If the app is to-be sold on VTEX App Store, the vendor is the one to profit from its installations.
If you're gonna use that app on multiple accounts, you don't need to request whitelist for every account as vendor.
This is one of the most important fields you need to fill on our whitelist request form, as it's gonna be determinant on our evaluation flow. It should be as descriptive as possible!.
It's an integration with a marketplaceIt's for developing components of this store
This app will integrate a VTEX Storefront with Instagram API, making possible for the merchant to display its latests Instagram posts and stories. It will also allow style customization via Admin. We also need a backend service because of API quotas of the external service, since an application key is necessary for high usageThe account I'm targetting with this app needs a frontend component to show the nearest physical store to the customer. Using the browser's geolocalization API, it fetches all the pickup points availabe on vtex.store-graphql and it displays the nearest one
If you have question about our guidelines, feel free to reach us at store-discussion!