The manifest.json file is the first communication point with VTEX IO, holding important metadata about an app, such as its name, version, vendor, description, dependencies, etc.

Hence, keep in mind that every IO app must have a manifest.json file on its root folder.

Check the following snippet, which shows a manifest example and its supported fields.

Click on each field to learn more about it.

{
"name": "app-name",
"vendor": "vtex",
"version": "1.0.0",
"title": "App Name",
"description": "Brief description of your app.",
"builders": {
"react": "3.x"
},
"scripts": {
"postreleasy": "vtex publish --verbose"
},
"dependencies": {
"vtex.styleguide": "9.x"
},
"peerDependencies": {
"vtex.store": "2.x"
},
"policies": [...],
"settingsSchema": {...},
"credentialType": {...}
}

For a real example of a manifest.json file, check this file.

The app name. It should concisely express the app's purpose.

On the VTEX IO platform, apps' names are kebab case. Basically, they must be comprised of lowercase letters separated by hyphens. Special characters, such as * and @, and numbers at the beginning of the name are not recommended.

The app owner. That is, the VTEX account responsible for the app development, maintenance, and distribution.

If the app is to-be sold on VTEX App Store, the vendor is the one to profit from its installations. Therefore, remember the following: an app must have only one vendor. Even is the app is installed on multiple accounts, you shouldn't change the app's vendor value for each one of them.

The app version, according to the Semantic Versioning 2.0.0.

The app distribution name. This name is the one used in the Apps section from the Administrative Panel and in the VTEX App Store.

A brief description explaining the app's purpose.

The list of builders used by the app. A builder is an abstraction to configure other IO services, such as node, dotnet, react, etc. It acts as an API service, responsible for processing and interpreting a directory from the app. Hence, it’s possible to use as many builders as you want in one single app.

For example, if you want to develop React components on an app, you should use the builder react@3.x, declaring it on the manifest:

"builders": {
    "react": "3.x"    
}

And create a react folder inside the app, placing there the component files. Each builder has its own set of rules and validation process.

Follow this link to learn more about Builders.

The list of scripts the app runs.

The list of other VTEX IO apps that the app relies on to properly work.

The most recurrent use of VTEX IO apps as dependencies are for:

• Using VTEX Store Framework blocks.
• Importing React components from another app.
• Importing Typescript types from a GraphQL service app.
• Using GraphQL or REST definitions declared in another app.
• Implementing a GraphQL schema from another app.

Follow this link to learn more about Dependencies.

The list of other apps that the app relies on to properly work. However, unlike regular dependencies, peer dependencies are not automatically installed in an account. Hence, these are mostly used in cases an app relies on paid apps or a specific version of an app.

Follow this link to learn more about Peer Dependencies.

The list of policies, responsible for granting permissions to the app in case it needs access to external services or specific data from other sources, such as external APIs.

Follow this link to learn more about Policies.

The layout settings of the app, displayed in the VTEX Admin.

Using JSON Schema, it’s possible to accept multiple fields with multiple data types. The persistence of the information is taken care by the VTEX Platform, and you may fetch the current configuration on your app code.

For example, on the vtex.wordpress-integration app, the following settingsSchema:

"settingsSchema": {
    "title": "Wordpress Integration",
    "type": "object",
    "properties": {
      "endpoint": {
        "title": "Wordpress URL",
        "description": "Enter the URL of your Wordpress installation in the form http://www.example.com/",
        "type": "string"
      },
      "titleTag": {
        "title": "Title tag for blog homepage",
        "description": "Will also be appended to inner blog pages",
        "type": "string"
      },
      "blogRoute": {
        "title": "URL path for blog homepage",
        "description": "Example: if 'foo' is entered here, blog homepage will be at http://www.yoursite.com/foo . Make sure routes in your store-theme match this setting. If left blank, default is 'blog'",
        "type": "string"
      }
    }
  }

will generate the following form once that app is installed:

Deprecated field.

The credential type. When set as relative, a request from the app can only be performed if the app and the role who called it have the required permissions. When set as absolute, if the app has the necessary permission, a request from the app can be performed.