Documentation
Feedback
Guides
App Development

App Development
Project structure
Builders
Store builder

Learn how to use the VTEX IO Store builder.

The store builder enables the development of Store Framework storefronts, empowering the development of both storefront components and unique store themes. The main use cases of the store builder include:

  • Frontend apps: When used alongside the react builder, the store builder allows integrating a frontend component with Site Editor. It enables mapping a React component to a block, grouping store blocks, and defining route handling within a component.
  • Store Theme apps: Defines block usage and store routes.

Note that if your store uses a different storefront solution, the store builder is not necessary, as this builder is specifically designed for developing apps for Store Framework.

This builder interprets and validates the blocks, interfaces, and routes within the /store folder.

With the store builder, you can use VTEX IO capabilities to quickly build store components and themes that can be reused across ecommerce stores and interact seamlessly with VTEX APIs and existing components.

Folder structure

An app that uses the store builder has a folder named /store in its root directory. The directory structure may vary depending on the specific project settings.

The basic structure of a /store folder is composed of the following files, as you can see in the store repository:


_10
store
_10
┣ 📄 blocks.json
_10
┣ 📄 contentSchemas.json
_10
┣ 📄 interfaces.json
_10
┗ 📄 routes.json

  • blocks.json: Declares all blocks that exist in your project. Note that blocks can be defined both in the store/blocks.json file or in any number of .json files organized within the store/blocks directory, using an arbitrary directory structure.
  • contentSchemas.json: Follows the JSON Schema format.
  • interfaces.json: Establishes a relationship between blocks and React components. Learn more in Interfaces.
  • routes.json: Creates custom routes in your app, mapping page templates to the path they will respond to. When developing store themes, see Creating a custom page for more information.

Usage

To use the store builder in your app, follow these steps:

Add the store builder to your app’s builder list in the manifest.json file, as follows:


_10
"builders": {
_10
"store": "0.x"
_10
}

In the root directory of your app, create a /store folder.

If you are developing a store theme with Store Framework from the Store Theme boilerplate, the store builder is natively installed, along with the /store folder.

Use case examples

Every store theme developed using Store Framework requires the store builder. Moreover, the store builder is also used in the development of any Store Framework component.

Below, you can check both scenarios.

Store theme

When creating a Store Framework storefront project, the first step is installing the Store Theme boilerplate. This process automatically installs the store builder in the manifest.json file.

Next, you can check the file structure of the Store Theme app:


_16
store
_16
┣ 📂 blocks
_16
┗ 📂 footer
_16
┗ 📂 header
_16
┗ 📂 home
_16
┗ 📂 pdp
_16
┗ 📂 product-summary
_16
┗ 📄about-us.json
_16
┗ 📄contact.jsonc
_16
┗ 📄faq.jsonc
_16
┗ 📄minicart.jsonc
_16
┗ 📄orderplaced.jsonc
_16
┗ 📄product-price.jsonc
_16
┗ 📄search.jsonc
_16
┣ 📄blocks.json
_16
┣ 📄routes.json

  • The blocks folder contains the Store Components installed by default, such as footer, header, home, minicart, search, among others.
  • The blocks.json file defines the organization and structure of different blocks that compose the storefront project.
  • The routes.json file defines custom routes for different sections of the storefront project, such as store.custom#about-us, store.custom#faq, and store.custom#contact-us, providing the path where the content related to that route can be accessed.

For more information on building a store theme with Store Framework, check the Storefront documentation.

Frontend components

The store builder is also necessary when developing a frontend app for use within a Store Theme app. Typically, such an app also leverages the react builder. For example, consider the Product Summary app.

The Product Summary app summarizes product information, including its name, price, and image.

Next, you can check the structure of the store folder for the Product Summary app:


_10
store
_10
┣ 📄 blocks.json
_10
┣ 📄 contentSchemas.json
_10
┣ 📄 interfaces.json

Within each of these files, there is a JSON structure, as follows:

  • blocks.json: Outlines the composition of a product summary component, specifying how different elements, such as image, name, attachments, price, and buy button should be arranged within various layouts (shelf and flex).
  • contentSchemas.json: Defines the properties and settings for two types of components related to product summaries, “ProductSummary” and “ProductSummaryList”. This includes specifying text labels, badge information, and positional details for integration with Site Editor.
  • inferfaces.json: Maps a React component from the react builder to a block definition.
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