How to Upgrade Your Theme and SDK | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to upgrade your experience theme and Search UI SDK version
• Common issues encountered during theme upgrades
• How to apply a diff to get patch changes

Overview

Now that you know what a new library version is, you’re probably wondering how you can upgrade your experience to take advantage of new features. Upgrading the theme version and Search UI SDK version is pretty easy. The Search Jambo Repository is built in such a way that the theme is self-contained, so updating the theme is just a matter of updating the files in the themes directory in the Search frontend Code Editor.

Generally, we recommend upgrading to take advantage of new features as they’re released. If you’re not interested in the new features in a major or minor release, you can also choose to skip it.

At a high level, the steps to upgrading your theme are:

• Create a branch to do the theme upgrade on.
• Read through theme/Search UI SDK release Community posts for each version from the current version to the latest version. Review the changes and upgrade instructions outlined in the post.
• Run the Tools > Jambo Commands > Upgrade Theme command for the system to upgrade the files in the theme folder.
• Upgrade the Search UI SDK version if there is a new one available with the new theme.
• QA your site via Live Preview and compare to your Staging site to see if there are any unwanted changes. You may need to redo or copy over any custom work where you overrode the theme.
• Commit your changes, merge into the master branch, and push to Production. Then you’re done!

Are you unsure about a particular step in the upgrade instructions, or need some clarification about how a new feature will impact your current experience? The Community is a great place to ask these questions, whether that’s commenting on the release post or writing a new one yourself!

Custom Work

Consideration Before Beginning: If custom work was previously done on your Search experience by a developer, this could potentially be a more complex theme upgrade. If possible, you should reach out to the developer to upgrade.

Custom work refers to any forked files outside of standard customizations we walk through in the Core Frontend modules, such as adding cards and pages. Remember that breaking changes can occur when you upgrade the theme if top-level files are outdated and are not compatible with new theme files, so you’ll want to check any custom work carefully. One way to identify custom work is to see if your experience has files that are not included in an out-of-the-box experience. You’ll notice many of the theme files and folders don’t exist at the top-level, outside of the theme. To see this, browse through the themes folder on the left of your Code Editor or using the Jambo command to Override Theme. Here are some common files and folders that may indicate custom work if you see that they exist outside of the theme:

• Any files in the partials directory (which typically only has a blank .gitkeep file)
• Any files in the static/js directory (which typically only contains a blank formatters-custom.js file for you to write custom formatters in)
• Any files in the layouts directory (which typically only contains blank files for footer.hbs, header.hbs, and headIncludes.hbs - a common file that could have been forked is html.hbs)
• A script folder (a common file that could have been forked is core.hbs)
• A templates folder
• A theme-components folder
• A universalsectiontemplates folder

Steps to Upgrade Your Experience

To upgrade the theme and Search UI SDK versions, follow these steps:

Step 1: Create a branch off of the master branch.

You can also use another branch you want to work off of. It is best practice to create a separate branch in case things go wrong and it takes a while to debug the issue. It is much easier to debug or redo the theme upgrade if it’s not on the master branch!

In the Code Editor screen, hover over that branch, click the three dots, and select Create new branch.

Name it something intuitive like “theme-upgrade-1.25”. You won’t be able to rename or delete branches.

Do not select a template for the new branch. Doing this would start the branch from a fresh template, but you want to pull from this site’s master branch.

Click Create Branch and then click the into the newly created branch to open the Code Editor.

Step 2: Check which version of the theme you are currently on.

To do this, open package.json in your Code Editor and look for the version number (the experience in the screenshot below is on version 1.22.0). The steps to upgrade your theme will depend on what version of the theme you are currently on.

Note: If you’re on a legacy theme (aka an old version before v1.10), do not attempt to upgrade. Legacy themes have a different file structure and upgrading is much more involved and manual. Reach out to your Admin or through the Hitchhikers Community.

Step 3: Complete pre-work for themes older than v1.16.

If your site was created before October 15th, 2020 or is on a theme older than v1.16, you’ll need to update to a newer node version. Complete the Theme v1.16 pre-work steps. Then commit your work and make sure the build is successful (if not, post in the Community). Refresh the Code Editor before moving on to the next step.

Step 4: Gather the relevant Community posts.

Upgrade instructions and implications are posted in the Community. Gather the Community posts for every version between the one you are currently on (or Theme v1.17, whichever is newer) to the version you’re upgrading to (most likely the latest version). Any new Search UI SDK versions will be included in the same posts.

Find these posts in the Community on the Answers Hitchhiker Theme - Changelog or the theme-upgrade tag .

Step 5: Read through the upgrade considerations thoroughly.

Review the callouts for every version and take note of whether you’ll need to take action on any of them and whether you need to do them before or after upgrading the theme. Types of upgrades include re-forking certain files and adding CSS variables to the answers-variables.scss file.

Step 6: Make any changes needed before upgrading the theme.

For example, we may have updated the cards in the theme, which means if you’re using theme cards, you’ll be using our latest and greatest recommendations when you upgrade. If you want to keep your cards as they are or do something different, you can always override the card before running the theme upgrade to get the card layout at that moment in time.

Step 7: Upgrade the theme by running Tools > Jambo Commands > Upgrade Theme.

This will update all the files in the themes/answers-hitchhikers-theme directory to the latest theme files.

Leave the branch of theme to upgrade to as “master.” Remember that the theme is also a repository of files and this is asking which branch of the theme you want to update to.

Leave the boxes for “Is Legacy Upgrade” and “Disable Upgrade Script” as is. You will not need to use these. Reach out in the Community for help if your experience is on a legacy theme (theme versions before v1.10).

Click Submit. This might take a minute to load as all the changes process.

The system will stage all of the changes for you so you may see as many as 300 files set to be updated, depending on how many theme versions you’re moving through. Don’t let that scare you!

Note: If you click into the global_config.json or package.json files, you’ll get a File Conflict popup. The theme upgrade changes these top-level files and the popup asks whether you want to allow the theme upgrade to make changes to top-level files or if you want to Keep Local Changes. Click Cancel to use the theme upgrade changes made to that file.

Step 8: Update the Search UI SDK version to pull in new product features.

If there is a new Search UI SDK version tied to the new theme version, update the sdkVersion in global_config.json by manually changing the number in the file. See the latest Search UI SDK version in the Search UI SDK Changelog (remember to pin to a minor like 1.7, NOT a patch like 1.7.1).

Step 9: Restart Live Preview.

Open the Console by clicking on Tools > Console to open the console log. Click Restart Live Preview in the top right, particularly if you are running into any errors, such as the child compilation errors within the screenshot below. You may need to restart your preview multiple times if you keep experiencing errors (particularly if you are making a big jump in theme versions). There may be some dependencies that need to reload.

Monitor the console log to make sure a) the changes are processing and b) to see if any errors surface. The console may call out certain files that are breaking. This is a good indicator of files that may be outdated or have errors.

Live Preview has successfully restarted when you see the line “Done”. Click View Live Preview to open a new preview tab or do a hard refresh of an existing Live Preview tab to see the new changes.

Note: Hard refresh by pressing command + shift + R on a Mac or control + F5 on Windows.

Step 10: Reconcile any previously overridden files.

Ensure they appear as they should and incorporate any theme upgrade changes. Follow the notes in each Community post on which files you need to re-fork.

Remember that any files you overrode before upgrading the theme will not automatically have updates from the theme upgrade. You will have to manually add these yourself (which you should do to stay up-to-date on new features unless you deliberately don’t want the new features) by either:

1. Overriding the theme file again and adding in the changes you had made previously. You’ll notice some theme Community posts may tell you to do this with certain files.

2. Referencing the theme file and copying over the whole file (and adding in the changes) or just new lines of code (only recommended for small changes where you know exactly what changed).

For example, if your starting theme version was below v1.14 and you’re using facets or sorting, you’ll need to add collapsible filters to your experience. You’ll follow Scenario B in the linked Community post, with the option to either:

1. Recreate the vertical pages by using the Jambo command to Add Vertical. Then make any adjustments you had made previously in your pages.

2. Copy-paste from the default page files in the theme.

Keep Live Preview and the Console open to make sure the changes come through as expected. You’ll also do more thorough QA in Step 12.

Step 11: Add any new features from recent themes you want to take advantage of.

Follow the instructions to configure it and make sure you see the changes in your experience. For example, you may want to add the loading indicator from Theme v1.23 to each of the pages in your Search experience.

Step 12: Test Live Preview thoroughly to ensure it works and functions how you expect.

Follow the steps outlined in the QA Your Experience module. Since your changes were only on the frontend, you can skip the search quality QA and focus primarily on browser and feature QA, as well as user interface QA. Some common things to check for are:

• Run through queries that surface results for each vertical and compare side by side with your staging or production link. Make sure to check a) all verticals searches and universal search, and b) both mobile & desktop views.
• If you added any custom CSS, it’s possible there may be some impact to your styling after upgrading your theme as HTML class names or structures may have changed.
• Any other custom work added to the experience.
• If there are any visual theme upgrade changes that are automatically applied to all experiences, make sure you see the changes in your experience. For example, Theme v1.25 fixed a styling regression where the variable --yxt-color-text-primary did not change the paragraph font color on cards. Once you upgrade, check that the paragraph font color is using this variable.

Note: You might be wondering why you need to go through such a thorough QA process again. It’s important to recognize that sometimes upgrades may also include breaking changes or regressions. Our Product team will make note of any breaking changes or regressions that they’re aware of in the release post. Take a look at the JS Version 1.1.0 Release post to see an example of what this might look like! However, it’s critical that you thoroughly QA your experience to confirm that it’s functioning as you’d expect and that there are no regressions or breaking changes that the Yext team is unaware of.

Step 13: Commit your changes once the Live Preview looks good.

Make sure to add a commit tag. Monitor the deploy on the Deploys screen to make sure it goes through successfully.

Step 14: Merge your branch back in with Master.

On the Code Editor branches screen, hover over the new theme upgrade branch, click the three dots, and select Merge Branch.

On the pop-up screen, select the branch you want to merge to, typically master. Then click Merge Branch.

On the next pop-up message, click Force Push to overwrite the contents of the master branch with your current branch. Remember you’ll want to QA your changes before you merge your branch into master - you don’t want to overwrite it with changes that don’t work!

Step 15: Check changes were applied to the master branch.

Before clicking into the master branch, you should notice there are new commits on the master branch: any new commits made to the theme upgrade branch you merged into master and a “Force Merge Branch”.

In the screenshot below, you’ll see there are two new commits compared to a similar screenshot in step 1. You’ll also notice that a legacy-master branch was created in the branch merge process. You don’t have to worry about this and don’t need to go into this branch.

If going into the master branch opens a previous session for you, terminate the session. Since the session was created before the changes you just committed, you’ll need to essentially refresh the code editor and pull in the changes you just made. Once you’re taken back to the Code Editor branches screen, click back into the master branch.

Double check the package.json file has the updated theme version. Open live preview and check that the changes carried over, similar to the QA you did in step 12.

Step 16: Publish the deploy for the theme upgrade to Production.

This pushes the theme upgrade live on the production site! Once published, do some light testing on the production link to ensure the merge itself went through successfully.

You’re done with upgrading your experience!

Common Upgrade Issues

Remember, the Community is a great place if you have any questions about upgrades or issues doing your own upgrade! Start by searching the Community for the error - others may have run into it before and posted a solution. If you can’t find your specific issue, feel free to post in the Community yourself and someone will help you debug it. Including screenshots of your console errors (both in the Code Editor and Live Preview) will help us help you!

Live Preview console errors show “Error updating component” + “Caused By: [Item] could not be found”.

Solution: Make sure to update to the latest SDK in the global_config.json file. This is erroring because the Hitchhiker Theme is trying to reference Search UI SDK components that are not available in the version of the Search UI SDK currently being used in the Search experience. Once you manually update the version number, be sure to click Restart Live Preview.

Changes don’t show up on the master branch after you merged the theme upgrade into the master branch.

Solution: Check the recent commits on the master branch include a “Force Merge Branch” commit and any new commits made to the theme upgrade branch you merged into master. If these exist, terminate the session when you click into the master branch and start a new session. If these don’t exist, merge the theme upgrade branch into master.

Changes don’t show up in the Live Preview / staging link / production link.

Solution: Be sure to hard refresh the page you’re looking at to pull in the changes. Hard refresh by pressing command + shift + R on a Mac or control + F5 on Windows. This clears the cache on the page, which could display a previous version of the page instead of the updated one with your changes.

Patches - Apply a Diff

Remember from the semantic versioning convention we use that patches can include bug fixes, including for styling regressions. There may come a time when you want to add a particular bug fix to your experience to target a specific issue without doing a full theme upgrade. You can do that easily via Tools > Apply Diff. This is also a great way to share updates between your repos or share a cool update with a colleague.

Use Case: Let’s say your Search experience is on Theme v1.22.0 and the latest version released is 1.25.0. However, you realize that Theme v1.22.1 includes a fix so that analytics events are fired when rich text field links are clicked in a result card. This is important to your experience, but you don’t want to do a full theme upgrade to 1.25.0. You can apply a diff!

Steps to Applying a Diff

You’ll notice that these steps are similar to the steps above for upgrading your experience. That’s because this is a partial upgrade and you’ll want to follow similar steps to prepare for and then QA your experience.

1. Check which version of the theme you are currently on by looking in the package.json file.
2. Find the Community post for the patch you would like to add to your experience.
3. Read through the upgrade implications thoroughly and note any actions you may need to take before or after applying the patch.
4. Make any changes needed before applying the patch, such as overriding any standard cards you want to keep as-is if the upgrade will change them.

5. Click on Tools > Apply Diff in the top right of your Code Editor.

   

6. Select the diff file you want to apply by entering the URL of a diff file or uploading a diff file (click Upload). For standalone features or bug fixes, you may find the diff URL in the Community post. Don’t see one that you need? Comment on the post and ask for it!

   

   Click View to preview the changes that will be applied. Click Apply to apply the changes.

7. Make any changes needed after the diff file is applied, including:

   • Re-forking certain files as directed to in the upgrade implications of the patch Community post.
   • Following any instructions in the Community post needed to configure the patch update.

8. Test Live Preview thoroughly to ensure it works and functions how you expect it would.

9. Commit your changes once Live Preview looks good. Then publish the commit to Production and do some light testing.

10. You’re done!