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, thestore
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:
_10store_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 thestore/blocks.json
file or in any number of.json
files organized within thestore/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:
_16store_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 asfooter
,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 asstore.custom#about-us
,store.custom#faq
, andstore.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:
_10store_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 thereact
builder to a block definition.