VTEX Developer Portal

Builders

A Builder is responsible for processing, validating, and forwarding a given block of code to a runtime or a framework capable of executing it.

In practice, a builder works as an API responsible for configuring other IO services.

As you'll see in the following, builders can also be understood as the entry points to the functionalities of an IO app.

In fact, the whole app implementation must relate to the builders declared in the app's manifest.json file and live inside the folders named over the app's builders.

When running an IO app, each builder converts the files included in its corresponding folder into configurations to the competent services. Check our implementation example.

Notice that each builder has its own set of rules and validation process.

One important aspect is that an app can have as many builders as you want. That allows bundling front and backend development and delivering your solution with just one package.

Notice that by dividing responsibilities into smaller builders, we are able to evolve them separately - quickly and with fewer stop-the-world breaking changes. Thus, it's expected from a builder to:

  • Have very well-defined and minimal responsibilities.
  • Be abstract and opinionated according to its goals.
  • Allow fine-grained permission control.

We currently work with several builders that simplify app development by making each part of an app's responsibilities clear and well separated. Check our list of builders.

Implementation example

Pretend you want to develop a React component in your IO app.

For that, you'll need to use a builder that offers a way to configure a React renderer, namely, the [email protected] builder.

To do that, you must declare the [email protected] builder in the app's manifest.json file, as in the following:

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

Then, in your app's root directory, you must create a folder named over the builder (e.g., /react) and place there the files you want its respective builder to compile (e.g., React component files).

When running your app, the [email protected] builder will transform the source code of TypeScript React components, placed inside the /react folder, into compiled bundles, ready to be imported into render apps.

List of builders

The VTEX Product Team is always improving how our builders work and creating new ones to ease the development of commerce solutions.

This is a non-exhaustive list of the VTEX IO builders:

NameFunctionality
adminExports blocks and routes to the VTEX Admin.
assetsHandles assets used by store theme blocks. It gets all asset paths used and uploads them to the VTEX IO database. You can learn how to use it by accessing the recipe on Using the Assets Builder.
configurationAllows you to allocate code pertaining to service configurations to an app that's independent of the platform. You can learn how to use it by accessing the recipe on Developing service configuration apps.
docsMakes the app documentation stored in /docs/readme.md available on VTEX IO Docs.
dotnetInterprets the /dotnet directory, empowering the development of custom backend services.
graphqlProcesses GraphQL API's and schemas by interpreting .graphql and .gql files contained in the app's /graphql directory.
stylesExports CSS configurations for Store Framework blocks. When building your app, the Styles builder reads the styles/styles.json file and uses a Tachyons generator to properly produce your store's CSS.
storeInterprets and validates the blocks, interfaces and routes contained in the theme app's /store directory, powering Store Framework store's components and building the storefront.
messagesExports localized string messages, empowering VTEX IO internationalization. It reads .json files associated with different locales within the app's /messages directory and makes them available for front-end applications to use via react-intl.
nodeInterprets the /node directory, empowering the development of custom backend services using Typescript.
pixelProcesses the source-code and configuration of Pixel Apps in VTEX IO. The files picked up by this builder are located in the app's /pixel directory.
reactInterprets the /react directory, empowering the development of React components using Typescript

Updated 10 days ago


Builders


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.