Documentation
Feedback
Guides

Contributing

VTEX IO is an open-source project. Contributions of all kinds are welcome, including feature requests, bug reports, and updates to our codebase and documentation.

Codebase

VTEX IO native apps are fully stored in the VTEX Apps Organization on GitHub.

That means you can contribute to our codebase by looking for the desired app on the VTEX Apps Organization and then opening an issue or creating a Pull Request.

When looking for an app on the VTEX Apps Organization, keep in mind that the name of VTEX IO apps are kebab case. That means they are comprised of lowercase letters separated by hyphens. Therefore, if, for example, you want to contribute to the Product Summary app you must look for product-summary on the VTEX Apps Organization.

Opening an issue

There are three main situations you should opt for opening an issue:

  • Report a bug you can’t solve by yourself.
  • Request a new feature or suggest an idea.
  • Ask questions you had during development.

{"base64":"  ","img":{"width":1499,"height":318,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":23889,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/contributing-0.png"}}

Once you open an issue, our team will evaluate your contribution as soon as possible.

Filtering issues

We use GitHub tags to classify issues between Questions, Bugs or Enhancements. This way, you can filter issues by specifying a label and author.

{"base64":"  ","img":{"width":302,"height":562,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":43877,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/contributing-1.png"}}

{"base64":"  ","img":{"width":301,"height":534,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":48880,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/contributing-2.png"}}

You can also change the sort criteria for the issues. For example, you can look for the most and least commented issues, the ones with most 👍 and most recently updated.

{"base64":"  ","img":{"width":297,"height":400,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":25617,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/contributing-3.png"}}

Creating a Pull Request

We recommend creating a Pull Request for trivial fixes or if you have already started working on a specific solution.

To create a Pull Request, take the following steps:

  1. Fork the desired repository and create a local clone of it.
  2. Create a branch from master, respecting the following name pattern: <type>/<description>, where description must provide a brief description of what is being developed and type must be one of the following:
  • feature - new feature or behavior.
  • fix - bug fix.
  • update - dependecy update.
  • chore - technical adjustments.

_10
git checkout master
_10
git checkout -b feature/nice-new-thing

  1. Commit changes to your new branch.

_10
git commit -m "Add nice new thing"

  1. Test your changes.
  2. Create a Pull Request. Make sure to include screenshots and a comprehensive description of the changes performed.

Once you open a Pull Request, our team will evaluate your contribution as soon as possible.

Documentation

There are three main ways to contribute to VTEX IO documentation:

  • Giving feedback - start a discussion regarding a specific document and leave quick suggestions.
  • Creating a Pull Request - work directly on a solution for improving a specific document and create a Pull Request.
  • Writing new documentation - keep up with our best practices and write the documentation of your custom app.

Giving feedback

Fill out our 📣 Feedback form and leave your suggestions on how we can improve a specific document.

Responses to the form are automatically added to our internal backlog and assigned to the team concerned. If you ask for a follow-up, we will let you know once we have addressed your feedback.

Creating a Pull Request

All guides, references, and tutorials from the VTEX IO Developer Documentation is fetched from the io-documentation repository.

In its turn, the documentation of VTEX IO apps are fetched directly from its corresponding GitHub repository.

App documentation is fetched only from apps using the Docs builder.

Therefore, you can create a Pull Request with your fixes directly on the io-documentation repository or on the repository of the corresponding app you want to contribute (e.g., product-summary)

Writing new documentation

To make the documentation of your custom app public on the Developer Portal, you must take the following steps:

  1. Create a docs/ folder in the app’s root.
  2. Update the app's manifest.json file to declare vtex.docs as one of the app's builders.

{"base64":"  ","img":{"width":636,"height":534,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":58068,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/contributing-4.png"}}

  1. Inside the docs/ folder create a README.md file.

    When writing the documentation of your app, make sure to follow our documentation templates.

  2. Contact us to make your documentation visible.

In order to not have to keep track of two README.md files (one in the project’s root and another it the docs/ folder), you can delete the former and only keep the latter. GitHub will read the one from the docs/ folder and render it on the landing page.

Documentation templates

React app README template

React app template


_115
📢 Use this project, [contribute](https://github.com/{OrganizationName}/{AppName}) to it or open issues to help evolve it using [Store Discussion](https://github.com/vtex-apps/store-discussion).
_115
_115
# APP NAME
_115
_115
_115
_115
_115
[![All Contributors](https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square)](https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/vtex-io/Hello/#contributors-)
_115
_115
_115
_115
_115
Under the app's name, you should explain the topic, giving a **brief description** of its **functionality** in a store when installed.
_115
_115
Next, **add media** (either an image of a GIF) with the rendered components, so that users can better understand how the app works in practice.
_115
_115
![Media Placeholder](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/contributing-5.png)
_115
_115
## Configuration
_115
_115
In this section, you first must **add the primary instructions** that will allow users to use the app's blocks in their store, such as:
_115
_115
1. Adding the app as a theme dependency in the `manifest.json` file;
_115
2. Declaring the app's main block in a given theme template or inside another block from the theme.
_115
_115
Remember to add a table with all blocks exported by the app and their descriptions. You can verify an example of it on the [Search Result documentation](https://developers.vtex.com/docs/guides/vtex-search-result/).
_115
_115
Next, add the **props table** containing your block's props.
_115
_115
If the app exports more than one block, create several tables - one for each block. For example:
_115
_115
### `block-1` props
_115
_115
| Prop name | Type | Description | Default value |
_115
| --------- | -------- | ----------- | ------------- |
_115
| `XXXXX` | `XXXXXX` | XXXXXXXX | `XXXXXX` |
_115
_115
### `block-2` props
_115
_115
| Prop name | Type | Description | Default value |
_115
| --------- | -------- | ----------- | ------------- |
_115
| `XXXXX` | `XXXXXX` | XXXXXXXX | `XXXXXX` |
_115
_115
Prop types are:
_115
_115
- `string`
_115
- `enum`
_115
- `number`
_115
- `boolean`
_115
- `object`
_115
- `array`
_115
_115
When documenting a prop whose type is `object` or `array` another prop table will be needed. You can create it following the example below:
_115
_115
- `propName` object:
_115
_115
| Prop name | Type | Description | Default value |
_115
| --------- | -------- | ----------- | ------------- |
_115
| `XXXXX` | `XXXXXX` | XXXXXXXX | `XXXXXX` |
_115
_115
Remember to also use this Configuration section to **showcase any necessary disclaimer** related to the app and its blocks, such as the different behavior it may display during its configuration.
_115
_115
## App behavior _(not mandatory)_
_115
_115
There are scenarios in which an app can behave differently in a store, according to how it was added to the catalog, for example. It's crucial to go through these **behavioral changes** in this section, allowing users to fully understand the **practical application** of the app in their store.
_115
_115
If you feel compelled to give further details about the app, such as it's **relationship with the VTEX admin**, don't hesitate to use this section.
_115
_115
## Customization
_115
_115
The first thing that should be present in this section is the sentence below, showing users the recipe pertaining to CSS customization in apps:
_115
_115
`In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization).`
_115
_115
Thereafter, you should add a single column table with the available CSS handles for the app, like the one below. Note that the Handles must be ordered alphabetically.
_115
_115
| CSS Handles |
_115
| ----------- |
_115
| `XXXXX` |
_115
| `XXXXX` |
_115
| `XXXXX` |
_115
| `XXXXX` |
_115
| `XXXXX` |
_115
_115
If there are none, add the following sentence instead:
_115
_115
`No CSS Handles are available yet for the app customization.`
_115
_115
_115
_115
## Contributors ✨
_115
_115
Thanks goes to these wonderful people:
_115
_115
_115
_115
_115
_115
_115
_115
_115
_115
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!
_115
_115
_115
_115
---
_115
_115
Check out some documentation models that are already live:
_115
_115
- [Breadcrumb](https://github.com/vtex-apps/breadcrumb)
_115
- [Image](https://vtex.io/docs/components/general/vtex.store-components/image)
_115
- [Condition Layout](https://developers.vtex.com/docs/guides/vtex-condition-layout/)
_115
- [Add To Cart Button](https://vtex.io/docs/components/content-blocks/vtex.add-to-cart-button@0.9.0/)
_115
- [Store Form](https://developers.vtex.com/docs/guides/vtex-store-form/)

Pixel app README template

Pixel app template


_59
📢 Use this project, [contribute](https://github.com/vtex-apps/CHANGEME) to it or open issues to help evolve it using [Store Discussion](https://github.com/vtex-apps/store-discussion).
_59
_59
# APP NAME
_59
_59
_59
_59
_59
[![All Contributors](https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square)](https://raw.githubusercontent.com/vtexdocs/dev-portal-content/main/docs/vtex-io/Hello/#contributors-)
_59
_59
_59
_59
_59
Under the app's name, you should explain the topic, giving a **brief description** of the **app's functionality** (what is it for?) in a store.
_59
_59
Next, you can **add media** (either an image of a GIF) if possible, so that users can better understand how the app works in practice.
_59
_59
![Media Placeholder](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/contributing-6.png)
_59
_59
## Configuration
_59
_59
It is possible to install in your store either by using App Store or the VTEX IO CLI.
_59
_59
### Using VTEX App Store
_59
_59
1. Access the **Apps** section in your account's admin page and look for the Icommkt box;
_59
2. Then, click on the **Install** button;
_59
3. You'll see a warning message about needing to enter the necessary configurations. Scroll down and type in your **NAME OF A SETTINGS FIELD** in the `NAME OF THE APP` field.
_59
4. Click on **Save**.
_59
_59
### Using VTEX IO CLI
_59
_59
1. [Install](https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-an-app/) the `vtex.icommkt@0.x` app. You can confirm that the app has now been installed by running `vtex ls` again.
_59
2. Access the **Apps** section in your account's admin page and look for the NAME OF THE APP box. Once you find it, click on the box.
_59
3. Fill in the `NAME OF THE APP` field with your **NAME OF THE SETTINGS FIELD**.
_59
4. Click on **Save**.
_59
_59
_59
_59
## App behavior _(not mandatory)_
_59
_59
There are scenarios in which an app can behave differently in a store, according to its configuration. It's crucial then to go through these **behavioral changes** in this section, allowing users to fully understand the **practical application** of the app in their store.
_59
_59
If you feel compelled to give further details, such as the app's **relationship with others**, don't hesitate to use this section.
_59
_59
_59
_59
## Contributors ✨
_59
_59
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
_59
_59
_59
_59
_59
_59
_59
_59
_59
_59
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!

Contributors
4
Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
4
Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
On this page