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.
_10git 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.
_10root_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:
| Field | Type | Description |
|---|---|---|
builders | object | Specifies 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. |
policies | array | Declares policies for accessing external services or specific resources needed for the app functioning. |
dependencies | object | Lists 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 file | Description |
|---|---|
/node/clients | Holds placeholder files for implementing custom VTEX IO clients. |
/node/handlers | Contains handler functions and logic designed to handle specific tasks and events. |
/node/utils | Holds global constants declarations (/node/constants.ts) and other utility fuctions. |
/node/index.ts | Encompasses 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.json | Describes 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:
| Field | Type | Description |
|---|---|---|
memory | integer | Memory size allocated to the app, in megabytes. This value is subjective to automatic adjustments if excessive usage is detected. |
timeout | integer | Maximum duration for fulfilling a request, in seconds. Requests exceeding this timeout are aborted. |
minReplicas | integer | Minimum number of replicas available when the app is operational. |
maxReplicas | integer | Maximum numbers of replicas available for the app. |
routes | object | Describes 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.
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:
| Field | Type | Description |
|---|---|---|
builders | object | Specifies 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. |
policies | array | Declares policies for accessing external services or specific resources needed for the app functioning. |
dependencies | object | Lists 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 file | Description |
|---|---|
/node/clients | Holds placeholder files for implementing custom VTEX IO clients. |
/node/handlers | Contains handler functions and logic designed to handle specific tasks and events. |
/node/utils | Holds global constants declarations (/node/constants.ts) and other utility fuctions. |
/node/index.ts | Encompasses 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.json | Describes 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:
| Field | Type | Description |
|---|---|---|
memory | integer | Memory size allocated to the app, in megabytes. This value is subjective to automatic adjustments if excessive usage is detected. |
timeout | integer | Maximum duration for fulfilling a request, in seconds. Requests exceeding this timeout are aborted. |
minReplicas | integer | Minimum number of replicas available when the app is operational. |
maxReplicas | integer | Maximum numbers of replicas available for the app. |
routes | object | Describes 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.
_10git clone https://github.com/vtex-trainings/service-course-template