Documentation
Feedback
Guides
App Development

App Development
ServicesDeveloping services on VTEX IO
1. Getting started with the boilerplate

The first thing you need to do is clone the service-course-template boilerplate, which is a template repository that we provide with all the initial files that you need to get started in this course.

Follow the step-by-step instructions to get started with the boilerplate and its dependencies.

Cloning the boilerplate repository

Clone the service-course-template boilerplate by running the command presented in the left. This will create a local copy of the project, equipping you with the necessary files to start the course.


_10
git clone https://github.com/vtex-trainings/service-course-template

Understanding the app structure

Open the service-course-template project in the code editor of your preference. You will notice the project contains three directories (/docs, /node and /graphql), the manifest.json file and the package.json file.


_10
root
_10
┣ πŸ“‚ docs
_10
┣ πŸ“‚ node
_10
┣ πŸ“‚ graphql
_10
┣ πŸ“„ README.md
_10
┣ πŸ“„ manifest.json
_10
β”— πŸ“„ package.json

manifest.json file

At the heart of this structure lies the manifest.json file, a crucial document encapsulating metadata about the app. This file not only contains fundamental details such as the app's name, version, and title but also outlines the builders, policies, and dependencies necessary for the app functionality. Let's delve deeper into some of these concepts:

FieldTypeDescription
buildersobjectSpecifies the builders required by the app. Note that the app uses the node builder, which is responsible for interpreting Node.js code. For each declared builder, there will be a dedicated folder specifically designed to be interpreted by that particular builder.
policiesarrayDeclares policies for accessing external services or specific resources needed for the app functioning.
dependenciesobjectLists other VTEX IO apps on which the app relies. For example, the app is dependent on the events-example app, which we will use in the following steps to trigger events.
manifest.json

_19
{
_19
"name": "backend-course",
_19
"vendor": "vtex",
_19
"version": "0.0.1",
_19
"title": "Backend Course",
_19
"description": "Reference app for the Backend Course",
_19
"builders": {
_19
"node": "6.x"
_19
},
_19
"scripts": {
_19
"prereleasy": "bash lint.sh"
_19
},
_19
"credentialType": "absolute",
_19
"policies": [],
_19
"dependencies": {
_19
"vtex.events-example": "0.x"
_19
},
_19
"$schema": "https://raw.githubusercontent.com/vtex/node-vtex-api/master/gen/manifest.schema"
_19
}

/node folder

The /node folder houses the backend logic of the app, written in Node.js. Here, Node packages and native libraries, such as @vtex/clients, can be employed to enhance code development.

In this project, our Node code is organized as in the following:

Folder or fileDescription
/node/clientsHolds placeholder files for implementing custom VTEX IO clients.
/node/handlersContains handler functions and logic designed to handle specific tasks and events.
/node/utilsHolds global constants declarations (/node/constants.ts) and other utility fuctions.
/node/index.tsEncompasses initial declarations for app functionality, such as cache and service declarations. This file will evolve throughout the course and also allow for the export of resolver function implementations for GraphQL.
/node/service.jsonDescribes the behavior of the service and attributes that impact the app's infrastructure.

Note that most of the directories are empty and will be filled throughout this course.


_10
node
_10
┣ πŸ“‚ clients
_10
┣ πŸ“‚ event
_10
┣ πŸ“‚ handlers
_10
┣ πŸ“‚ utils
_10
┣ πŸ“„ index.ts
_10
┣ πŸ“„ package.json
_10
┣ πŸ“„ service.json
_10
┣ πŸ“„ tsconfig.json
_10
β”— πŸ“„ yarn.lock

service.json file

Located within the /node folder, the service.json file configures the app's infrastructure attributes. Key details are summarized in the following table:

FieldTypeDescription
memoryintegerMemory size allocated to the app, in megabytes. This value is subjective to automatic adjustments if excessive usage is detected.
timeoutintegerMaximum duration for fulfilling a request, in seconds. Requests exceeding this timeout are aborted.
minReplicasintegerMinimum number of replicas available when the app is operational.
maxReplicasintegerMaximum numbers of replicas available for the app.
routesobjectDescribes the app's REST routes.
node/service.json

_12
{
_12
"memory": 256,
_12
"timeout": 2,
_12
"minReplicas": 2,
_12
"maxReplicas": 4,
_12
"routes": {
_12
"status": {
_12
"path": "/_v/status/:code",
_12
"public": true
_12
}
_12
}
_12
}

/graphql folder

The /graphql folder, though currently empty, will be used to house GraphQL-related files in the project. The /graphql/schema.graphql file is a common convention for storing the GraphQL schema definition. In a GraphQL schema, you define the types, queries, mutations, and subscriptions that your GraphQL service supports. As our app evolves, we will populate this file with our GraphQL schema.


_10
graphql
_10
β”— πŸ“„ schema.graphql

Cloning the boilerplate repository

Clone the service-course-template boilerplate by running the command presented in the left. This will create a local copy of the project, equipping you with the necessary files to start the course.

Understanding the app structure

Open the service-course-template project in the code editor of your preference. You will notice the project contains three directories (/docs, /node and /graphql), the manifest.json file and the package.json file.

manifest.json file

At the heart of this structure lies the manifest.json file, a crucial document encapsulating metadata about the app. This file not only contains fundamental details such as the app's name, version, and title but also outlines the builders, policies, and dependencies necessary for the app functionality. Let's delve deeper into some of these concepts:

FieldTypeDescription
buildersobjectSpecifies the builders required by the app. Note that the app uses the node builder, which is responsible for interpreting Node.js code. For each declared builder, there will be a dedicated folder specifically designed to be interpreted by that particular builder.
policiesarrayDeclares policies for accessing external services or specific resources needed for the app functioning.
dependenciesobjectLists other VTEX IO apps on which the app relies. For example, the app is dependent on the events-example app, which we will use in the following steps to trigger events.

/node folder

The /node folder houses the backend logic of the app, written in Node.js. Here, Node packages and native libraries, such as @vtex/clients, can be employed to enhance code development.

In this project, our Node code is organized as in the following:

Folder or fileDescription
/node/clientsHolds placeholder files for implementing custom VTEX IO clients.
/node/handlersContains handler functions and logic designed to handle specific tasks and events.
/node/utilsHolds global constants declarations (/node/constants.ts) and other utility fuctions.
/node/index.tsEncompasses initial declarations for app functionality, such as cache and service declarations. This file will evolve throughout the course and also allow for the export of resolver function implementations for GraphQL.
/node/service.jsonDescribes the behavior of the service and attributes that impact the app's infrastructure.

Note that most of the directories are empty and will be filled throughout this course.

service.json file

Located within the /node folder, the service.json file configures the app's infrastructure attributes. Key details are summarized in the following table:

FieldTypeDescription
memoryintegerMemory size allocated to the app, in megabytes. This value is subjective to automatic adjustments if excessive usage is detected.
timeoutintegerMaximum duration for fulfilling a request, in seconds. Requests exceeding this timeout are aborted.
minReplicasintegerMinimum number of replicas available when the app is operational.
maxReplicasintegerMaximum numbers of replicas available for the app.
routesobjectDescribes the app's REST routes.

/graphql folder

The /graphql folder, though currently empty, will be used to house GraphQL-related files in the project. The /graphql/schema.graphql file is a common convention for storing the GraphQL schema definition. In a GraphQL schema, you define the types, queries, mutations, and subscriptions that your GraphQL service supports. As our app evolves, we will populate this file with our GraphQL schema.


_10
git clone https://github.com/vtex-trainings/service-course-template

Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
1
Photo of the contributor
+ 1 contributors
On this page