To kickstart your journey in this course, your initial step is to clone the vtex.service-example boilerplate app. This repository serves as a template with all the essential files you need to get started in this course.
Cloning the boilerplate repository
Clone the vtex-apps/service-example boilerplate by running the command presented on the right panel. 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-apps/service-example
Understanding the project structure
Open the service-example project in the code editor of your preference. Note that the project contains the /node and /docs directories, the manifest.json file, and the package.json file.
_10root_10 ┣ 📂 node_10 ┣ 📂 docs_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, 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. |
node folder
The /node folder contains 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.
Within the node folder, you will also find the following folders and files:
| Folder or file | Description |
|---|---|
/middlewares | Folder containing middleware functions. |
/middlewares/validate.ts | Middleware that validates if the request has a valid HTTP status code. It will also be used to access the app authentication token. |
/middlewares/status.ts | Middleware to call the VTEX Commerce API and fetch SKU details from the Catalog API. |
/clients | Folder where the Clients of the app are defined, used to access external resources and services. |
/clients/index.ts | Definition of the Clients class. Here we will import the Client Catalog and define a getter/setter function for Catalog items. |
index.ts | Initial declarations for the app's functionality, including mapping routes and middlewares. |
package.json | Metadata about the node app, including its name, version, description, dependencies, and scripts. |
service.json | Configuration file that specifies the the app's infrastructure attributes. It includes details such as memory allocation, timeout duration, minimum and maximum replicas, and routes. |
tsconfig.json | Configuration file for TypeScript, specifying how the TypeScript compiler should compile the project. It may include options such as the target JavaScript version, module system, and other compiler settings. |
node/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. Note that a public route named status with the path /_v/status/:code is already defined. |
node/index.ts file
The node/index.ts file associates routes with middlewares. Note that the routes section associates the status route with the GET method and the validate and status middleware functions.
This means that when a GET request is made to the status route, the app will trigger the validate and status middleware functions in the specified order.
Check the
middlewares/status.tsandmiddlewares/validate.tsfiles to better understand the functions exposed by this service.
Testing the /status route
Change to the app directory and link it to a development workspace. This action will prompt the availability of the /status route. To verify its functionality, make a request to https://{workspace}--{accountName}.myvtex.com/_v/status/200, replacing {workspace} and {accountName} according to your scenario.
Cloning the boilerplate repository
Clone the vtex-apps/service-example boilerplate by running the command presented on the right panel. This will create a local copy of the project, equipping you with the necessary files to start the course.
Understanding the project structure
Open the service-example project in the code editor of your preference. Note that the project contains the /node and /docs directories, 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, 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. |
node folder
The /node folder contains 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.
Within the node folder, you will also find the following folders and files:
| Folder or file | Description |
|---|---|
/middlewares | Folder containing middleware functions. |
/middlewares/validate.ts | Middleware that validates if the request has a valid HTTP status code. It will also be used to access the app authentication token. |
/middlewares/status.ts | Middleware to call the VTEX Commerce API and fetch SKU details from the Catalog API. |
/clients | Folder where the Clients of the app are defined, used to access external resources and services. |
/clients/index.ts | Definition of the Clients class. Here we will import the Client Catalog and define a getter/setter function for Catalog items. |
index.ts | Initial declarations for the app's functionality, including mapping routes and middlewares. |
package.json | Metadata about the node app, including its name, version, description, dependencies, and scripts. |
service.json | Configuration file that specifies the the app's infrastructure attributes. It includes details such as memory allocation, timeout duration, minimum and maximum replicas, and routes. |
tsconfig.json | Configuration file for TypeScript, specifying how the TypeScript compiler should compile the project. It may include options such as the target JavaScript version, module system, and other compiler settings. |
node/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. Note that a public route named status with the path /_v/status/:code is already defined. |
node/index.ts file
The node/index.ts file associates routes with middlewares. Note that the routes section associates the status route with the GET method and the validate and status middleware functions.
This means that when a GET request is made to the status route, the app will trigger the validate and status middleware functions in the specified order.
Check the
middlewares/status.tsandmiddlewares/validate.tsfiles to better understand the functions exposed by this service.
Testing the /status route
Change to the app directory and link it to a development workspace. This action will prompt the availability of the /status route. To verify its functionality, make a request to https://{workspace}--{accountName}.myvtex.com/_v/status/200, replacing {workspace} and {accountName} according to your scenario.
_10git clone https://github.com/vtex-apps/service-example