Working with development branches

In this guide, you'll learn how to create and use a development branch to test schema changes without affecting your account's live content or merge and publish workflow.

A development branch is a temporary CMS branch used for testing. Unlike a regular branch, it's tied to its own schema version, so any content you create inside it uses that version instead of the one currently live in main. Because each branch carries its own schema version, multiple developers can test in parallel without interfering with each other or with the live schema.

You point the branch to a new or updated schema, create test content against it, and see exactly how that schema behaves, without touching production content or the live schema.

To work with a development branch, you need to have VTEX CLI and Content plugin (@vtex/cli-plugin-content) installed and be logged in to your account. Also, your user role must have the following associated with it:

1. Open your project in a code editor and make your schema changes.

2. Open a terminal and log in to your VTEX account by running vtex login {accountName}.

   Replace {accountName} with your store account, for example, vtex login mystore.

3. Generate your schema file by running:

   
   

   _10

   vtex content generate-schema --out cms_schema.json

   
   

4. Upload the schema by running:

   
   

   _10

   vtex content upload-schema ./cms_schema.json

   
   

5. When the CLI asks which version to associate with the schema, type the full version you want to publish, using a beta pre-release tag to avoid affecting the current live schema, for example, 1.7.0-beta.0.

   
   

   _10

   ✔ Schema version to publish (e.g. 1.2.0 or 1.2.0-beta.1, not already in the registry) 1.7.0-beta.0

   
   

1. Open the VTEX Admin and go to Storefront > Content > Branches.

2. Click + to create a new branch.

3. Enable the Development branch toggle.

4. Under Schema version, select the version you published in Step 1.

5. Click Create.

   

   Development branches can't be merged into main, so content built on a test schema can never accidentally reach the live store. Also, this type of branch is automatically deleted 15 days after creation.

1. Inside the development branch, create new versions of the entries you want to test.

2. Open a version to review it. Versions created in a development branch show a </> icon, so you can tell them apart from versions in main.

   Only users with the Manage Dev Branch permission can see these versions.

3. To preview content locally while testing, add a Preview URL to the version. This is useful, for example, when testing new React components against a local FastStore instance running on your machine. To do so, point the Preview URL to http://localhost:<port>/api/preview.