Developing service configuration apps

Learn how to create standalone apps dedicated to configuring services within the VTEX IO platform.

This guide will walk you through the process of creating standalone apps dedicated to configuring services within the VTEX IO platform. By following these steps, you can enhance the adaptability and versioning of your VTEX IO apps.

To complete this guide, we will develop apps with two distinct purposes:

Service apps: These applications provide specific functionalities to other apps or users within the VTEX platform. They are what other apps configure to leverage particular features or services. Service apps are developed using either the node, dotnet or graphql builder.
Configuration apps: These independent applications are designed to configure Service apps. Their primary role is to define how a service app should behave, specifying settings and adapting its functionality to meet the needs of other apps or users. Configuration apps use the configuration builder, which separates service configuration code into an independent app, decoupled from the platform.

In the diagram below, you can see how Service and Configuration apps interact with each other. Service apps expose their schema configurations via the schema.json file, and Configuration apps utilize this information to manage and deliver configurations via the configuration.json file. This separation of concerns enhances organization and modularity in application development, especially in the context of configuration management.

Step by step

Step 1 - Creating a Service app

In this initial stage, you will create a Service app to house the service configurations for another VTEX IO app.

Open the terminal and use the VTEX IO CLI to log in to your VTEX account.

_10vtex login {accountName}
Start a new VTEX IO app project by running the following command.

_10vtex init
Select the service-example option.
Open the app project in your preferred code editor.

Step 2 - Configuring the Service App

Now, declare that your app can receive configurations through requests. Follow the instructions below based on your scenario:

Node service

In the node/service.json file, add "settingsType": "workspace" to define which routes will be able to receive configurations through requests. For example:


_10"routes": {
_10  "status": {
_10    "path": "/_v/status/:code",
_10    "public": true,
_10    "settingsType": "workspace"
_10  },
_10}

It is also possible to define your configurations through event listening. In this case, you should add in the node/service.json file something similar to the example below, replacing the values according to your needs:


_10"events": {
_10  "eventHandler": {
_10    "sender": "appEmittingTheEvent",
_10    "keys": ["topic"],
_10    "settingsType": "workspace"
_10  },
_10}

GraphQL app

If you are developing a GraphQL app, add the @settings directive to all queries that can receive configurations.

A GraphQL Directive is a way of changing how the query will be performed. When you add the settings directive, the system knows it must search for configurations for that service. Under the hood, this directive is including one extra step to the query, which is responsible for finding all the configurations and adding them to the context.

Take the graphql-example app as an example. In this app's root directory, you'll see the following file grapqhl/schema.graphql. Now, if you open it and add the @settings directive to the query book, you'll have something like:


_10 type Query {
_10-    book(id: ID!): Book
_10+    book(id: ID!): Book @settings(settingsType: "workspace")
_10 }
_10
_10+ @settings(settingsType: "workspace")

Step 3 - Setting up the `configuration` builder

Open the app's manifest.json file and add the configuration builder to the builders list. Also, update the name and vendor fields according your scenario. For example:

_10 { _10 "name": "vtex.most-amazing-service-ever", _10 "version": "0.0.0", _10 "builders": { _10 "node": "4.x", _10+ "configuration": "0.x" _10 } _10 }
Create a configuration folder in your app's root directory.
Create a file named schema.json inside the configuration folder. This file will hold information about the settings structure that the Service app is going to accept from other apps on the platform.
In the configuration/schema.json file, create a JSON Schema according to your scenario. The JSON Schema will be used to identify new configurations coming from apps and define the expected format of a new configuration. For example:

_10{ _10 "type": "object", _10 "properties": { _10 "id": { "type": "number" }, _10 "name": { "type": "string" } _10 } _10}

In the example above, the accepted configuration is an object with two keys: id and name, where the first is a number, and the second is a string.

Step 4 - Deploying the Service app

Save your changes and then deploy your new Service app.

Step 5 - Linking the Configuration app to the Service app

Once your Service app is deployed, it is ready to receive configurations from other apps.

Start a new Configuration app project.
Add the recently created Service app as a new builder to the manifest.json file of your new Configuration app. For example:

_10{ _10 "name": "vtex.amazing-configuration", _10 "version": "0.0.0", _10 "builders": { _10+ "vtex.most-amazing-service-ever": "0.x", _10 } _10}

Ensure that the name of the builder matches the Service you want your app to configure, and the version matches the desired Service app version. 2. Create a new folder named after your Service app and create a new file named configuration.json within it (e.g., vtex.most-amazing-service-ever/configuration.json). 3. In the configuration.json, define which service configurations are expected according to the JSON schema structure previously defined in the Service app. For example:


_10{
_10  "name": "little foot",
_10  "id": 19
_10}

Save your changes and then publish your new Configuration app version.

Reading the received Service app configurations

Understanding how to access configurations received by the Service app is crucial. As mentioned earlier, these configurations originate from other apps within the context of their respective requests.

To retrieve the configurations received by the Service app, use the following command:


_10const settings = ctx.vtex.settings;

The ctx can be either a EventContext or a ServiceContext.

The received configurations are structured as an array of objects, as demonstrated in the example below:


_10[
_10  {
_10    "vtex.amazing-configuration": {
_10      "name": "little foot",
_10      "id": 1
_10    },
_10    "declarer": "vtex.amazing-configuration@0.0.0+build1580823094"
_10  }
_10]

Each element in this array consists of:

An object containing the name of the app that configures the service (e.g., vtex.amazing-configuration) and the configuration schema's settings, adhering to the structure defined in the Service app's schema.json file.
The declarer key, which holds the full name of the app responsible for these configurations.

Note that multiple apps can configure the same service. Hence, each element in this array represents a configuration originating from a different app.

Troubleshooting

If you are developing a configuration app and the service that your app is configuring is not installed or linked in the same workspace you're working at, you may run into some errors. That happens because, when creating a new configuration app, the configuration builder first looks for the schema of that configuration in all the apps installed in your current workspace. Consequently, if the configuration builder cannot find this specific configuration, linking your app may fail.

To avoid errors, remember to always have the service you're configuring linked or installed in the same workspace you're developing your configuration app.

To publish your Configuration app without installing the service in the master workspace, you can link or install the Service app in an alternative branch and then use the -w flag when publishing:


_10vtex publish -w {alternativeBranchName}