VTEX Developer Portal

Migrating CMS settings after a theme major update

Migrating CMS settings after a theme major update

You may need to do a major update of your app store theme due to changes in its peer dependencies, for example. In this situation, however, changing to a new app store theme major could lead to undesired consequences, such as losing the page template settings in the admin.

To handle this situation, you have the option of migrating template settings by following the step-by-step presented in the sequence.

Step by step

  1. Using your terminal and the VTEX IO Toolbelt, publish the new major version of your app store theme.
  2. Log into the account which the theme is installed.
  3. Run vtex use {workspaceName} --production to create and use a new production workspace.

⚠️ Remember to replace the values between the curly braces according to your scenario.

  1. Run vtex install {appvendor}.{appname}@{appversion} to install the app store theme published in step 1.
  2. Run vtex install [email protected] to install the GraphQL admin IDE.
  3. In your browser, access your account's admin and select the GraphQL admin IDE in the side-bar menu.
  4. From the dropdown list, choose the [email protected] app.
  5. Copy the mutation command presented below to the text box that is displayed and update the from and to values according to your scenario.
mutation{
  updateThemeIds(from:"{appvendor}.{appname}@{oldmajor}.x", to:"{appvendor}.{appname}@{newmajor}.x")
}
  1. Open the workspace and validate content, routes, pages, and redirects.
  2. If everything goes as expected, promote your workspace to master.

Updated 10 days ago


Migrating CMS settings after a theme major update


Suggested Edits are limited on API Reference Pages

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