The Yext team periodically releases updates to the Search UI SDK (also referred to as the JavaScript Library or the SDK), which include new features, enhancements to existing features, deprecation of old features, and bug fixes. Yext also adds new functionality, new cards, and new page templates to the Hitchhiker Theme. To take advantage of new features, you need to upgrade both the Theme and the Search UI SDK in your Search experience.

Note: Solution templates are always on the latest Theme and Search UI SDK versions, so new sites built from them start with the latest version of Search.

Where to Find Information on Upgrade Versions

Below are the components that have upgrade versions, links to their changelogs, and where to update the version numbers.

All updates to the theme and SDK are posted in changelogs within the Search reference documentation. These posts outline changes and bug fixes for each version, including upgrade implications to be aware of. A new Search UI SDK version will always be tied to a new theme version, but the theme is updated more frequently than the SDK.

For example:

• Theme v1.24 outlines changes and new formatters, including files you may need to re-fork.
• Theme v1.23 and Search UI SDK 1.10 notes changes and upgrade instructions for both the theme and SDK.

Note on the search bar: The legacy search bar uses the same changelog as the Search UI SDK because they both use the same JavaScript library. However, the search bar version and the library version are distinct - they use different components in the library. Upgrading the library version does not require a corresponding update to the search bar version.

Why You Need to Update the SDK When Upgrading the Theme

The theme references the specific code from the SDK to build Search experiences. When you update the theme, you'll want to also update the SDK version the theme is working with. A new theme version updates the theme files to accommodate the changes in the SDK. Since the theme files are built directly off of the SDK components, you'll want to make sure they're compatible with each other by using the latest versions of both.

The Theme Folder vs Top-Level Files

The theme files can be viewed from any Search frontend Code Editor. Navigate to the themes/answers-hitchhiker-themes folder to see the files included in the theme.

Upgrading the theme (via Tools > Jambo Commands > Upgrade Theme) replaces the answers-hitchhiker-theme folder with an updated folder containing files for the latest theme version. Once you upgrade, click Restart Live Preview to review the updates.

Any files not in this theme folder are considered top-level files. Barring a few exceptions, top-level files are not touched when you upgrade the theme.

Because upgrading the theme replaces the entire answers-hitchhiker-theme folder, never update the theme files directly. Any direct edits will be overwritten the next time you do a theme upgrade. Instead, if you want to stray from the theme, override the file, which creates a top-level copy you are free to edit.

Note: You might see the terms "fork," "shadow," or "override" used interchangeably - they all mean making a top-level copy of the theme file to customize.

Breaking Changes

Breaking changes can occur when you upgrade the theme if top-level files are outdated and are not compatible with new theme files. Overriding the theme copies that file at that moment in time - if you upgrade the theme after a file has been overridden, that file will not automatically pull in updates. Only override the theme deliberately.

The changelog calls out which files to check for forked versions for each version. If you previously overrode the theme, you must manually add updates yourself by either:

1. Referencing the theme file and copying over new lines of code (only recommended for small changes where you know exactly what changed), or
2. Overriding the theme file again and re-adding the changes you had made previously.

Override Theme Files Using Jambo Commands

Pages and cards are common examples of files that may have been previously overridden and may need to be updated after a theme upgrade. Jambo commands such as "Add Page" or "Add Card" create new files using the theme templates from that moment in time. If you created pages or cards, you overrode the theme.

You can also use the Jambo command "Override Theme" to make an exact copy of a file in the top-level directory. The command automatically updates jambo.json to indicate you're providing an override.

Use the theme when you can to easily take advantage of new features as they come out. For example, if you fork and customize the allfields-standard card, you will not get card changes from future theme upgrades.

Theme Branches

When you upgrade the theme, it will ask which branch of the theme you'd like to upgrade to. Leave this on master to upgrade to the most recent version.

Upgrading the SDK Version

For the Hitchhiker Theme, use the Jambo Command "Upgrade Theme" to automatically upgrade to the latest version. When you upgrade the theme, the SDK is also automatically updated and the new version is populated in the global_config.json file.

Semantic Versioning

Yext releases updates to the Search UI SDK using semantic versioning, where versions are denoted by three numbers in the form of Major.Minor.Patch - for example, v1.21.2.

Patches (e.g., v1.21.2) - Non-breaking bug fixes, including styling regression fixes. When you upgrade patches, you will not see things degrade.

• Pinning to a patch means pinning to an exact version; you'll need to do work to upgrade to the latest patch.
• If you have custom styling targeting specific classes, patch updates might be breaking.
• Recommended for high-profile sites with strict protocols on changes and those with custom styling that could break with automatic updates.

Minor Versions (e.g., v1.21) - New functionality and deliberate styling updates. Will not stop your experience from working, but there is a chance of visual impact.

• Pinning to a minor version uses the latest public version starting with 1.21. This is recommended for most sites as it means you get patch fixes automatically.

Major Versions (e.g., v1) - Breaking changes such as a changed interface. Follow the reference doc associated with the SDK version closely for major version upgrades.

• Pinning to a major version uses the latest public version starting with 1. Not recommended for production experiences as it could be risky.

So long as you are not providing custom styling or doing custom development work, pinning to a minor version is recommended so you receive bug fixes automatically without redeploying your site.

When to Rebuild Instead of Upgrade

If it's been a long time since you've upgraded the theme (or if you've never upgraded it), you'll likely be jumping across many versions at once. In this case, instead of doing a theme upgrade, we recommend you rebuild your Search frontend altogether. This will be quicker and less tedious than checking for breaking changes in each version.

We recommend rebuilding if you are starting with theme version 1.10 or earlier. The rebuild process retains the domain and Yext Pages site currently in use and will not break your live site. See Rebuild Your Site below.

Custom Work Considerations

If custom work was previously done on your Search experience by a developer, this could be a more complex theme upgrade. If possible, reach out to the developer to upgrade.

Custom work refers to any forked files outside of standard customizations, such as adding cards and pages. To identify custom work, look for top-level files not included in an out-of-the-box experience. Common indicators include:

• 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)
• Any files in the layouts directory beyond the standard blank footer.hbs, header.hbs, and headIncludes.hbs (a common forked file is html.hbs)
• A script folder (a common forked file is core.hbs)
• A templates folder
• A theme-components folder
• A universalsectiontemplates folder

Step-by-Step: How to Upgrade the Theme

Step 1: Create a Branch

It is best practice to create a separate branch in case things go wrong. 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 the master branch, click the three dots, and select Create new branch.

Name it something intuitive like "theme-upgrade-1.25" using the latest theme version number. 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 rather than pulling from the site's master branch.

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

Step 2: Pre-Work for Theme Upgrade

There are a few things to do before you hit Upgrade Theme.

Check Current Theme Version: Open package.json in your Code Editor and look for the version number. The steps to upgrade will depend on what version you are currently on.

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 upgrade call out steps. Then commit your work, make sure the build is successful, and refresh the Code Editor before moving on.

Read Through the Upgrade Considerations Thoroughly: Review the callouts for every version between the one you are currently on (or Theme v1.17, whichever is newer) and the version you're upgrading to in the Hitchhikers Theme Changelog. Take note of whether you'll need to take action on any of them and whether they need to be done before or after upgrading the theme. Types of upgrades include re-forking certain files and adding CSS variables to the answers-variables.scss file.

Make Any Changes Needed Before Upgrading: For example, if the new theme updates cards you're using and you want to keep your cards as they are, override the card before running the theme upgrade to capture the card layout at that moment in time.

Step 3: Upgrade the Theme

Click Tools > Jambo Commands > Upgrade Theme.

This updates all files in the themes/answers-hitchhikers-theme folder to the latest theme files.

Leave the branch of theme to upgrade to as "master." Leave the boxes for "Is Legacy Upgrade" and "Disable Upgrade Script" as is. If you're on a legacy theme (before v1.10), we recommend rebuilding your site instead.

Click Submit. This might take a minute to load. The system will stage all changes for you - you may see as many as 300 files set to be updated depending on how many theme versions you're moving through.

File Conflicts: If you click into the global_config.json or package.json files, you'll get a File Conflict popup. Click Cancel to use the theme upgrade's changes to that file.

New SDK Version: If there is a new Search UI SDK version tied to the new theme version, the sdkVersion property in the global_config.json file will be automatically updated when you run the theme upgrade.

Step 4: Process Version Updates

Now that you've run the theme upgrade, complete any action items designated for after upgrading. There are two types: reconciling previously overridden files and adding new features you want to use.

Restart Live Preview: Open the Console by clicking Tools > Console, then click Restart Live Preview in the top right. You may need to restart multiple times if you are making a big jump in theme versions.

Monitor the console log to see if changes are processing and if any errors surface. Live Preview has successfully restarted when you see the line "Done."

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

Reconcile Any Previously Overridden Files: Ensure any previously overridden files appear as they should and incorporate theme upgrade changes. Files you overrode before upgrading will not automatically have updates from the upgrade. You'll have to manually add them yourself by either overriding the theme file again and re-adding your changes, or referencing the theme file and copying over new lines of code.

Example - Collapsible Filters: If your starting theme version was below v1.14 and you're using facets or sorting, you'll need to add collapsible filters. You can either recreate the vertical pages using the Jambo "Add Vertical" command and re-apply your previous adjustments, or copy-paste from the default page files in the theme.

Add New Features You Want to Use: Follow the instructions for any new features from the changelog you want to enable.

Step 5: QA Your Search Site

Since your changes were only on the frontend, focus primarily on browser, feature, and UI QA. Common things to check:

• Run through queries that surface results for each vertical and compare side by side with your staging or production link. Check all vertical searches and universal search, on both mobile and desktop.
• If you added any custom CSS, verify styling is intact - HTML class names or structures may have changed with the upgrade.
• Any custom work added to the experience.
• If there are visual theme upgrade changes that are automatically applied to all experiences, make sure you see them in your experience.

Note: Upgrades may include breaking changes or regressions. The Product team will note any known breaking changes in the release post, but you should still QA thoroughly to catch anything unexpected.

Commit Changes Once Live Preview Looks Good: Add a commit tag and monitor the deploy on the Deploys screen to make sure it goes through successfully.

Step 6: Push to Production

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

Select the branch you want to merge to (typically master), then click Merge Branch.

On the next popup, click Force Push to overwrite the contents of the master branch with your current branch.

Check Changes on Master Branch: Before clicking into master, verify there are new commits: any commits made to the theme upgrade branch and a "Force Merge Branch" commit. If going into the master branch opens a previous session, terminate it by clicking Tools > Terminate Session, then click back into the master branch. Double check package.json has the updated theme version.

Publish the Deploy to Production: This pushes the theme upgrade live on your production site. Once published, do some light testing on the production link to ensure the merge went through successfully.

Common Upgrade Issues

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

Update to the latest SDK in the global_config.json file. The Hitchhikers Theme is trying to reference Search UI SDK components not available in the current SDK version. Once you manually update the version number, click Restart Live Preview.

Changes don't show up on the master branch after merging.

Check that the recent commits on master include a "Force Merge Branch" commit and commits from your theme upgrade branch. If they exist, terminate the current session and start a new one. If they don't exist, merge the theme upgrade branch into master.

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

Hard refresh the page (command + shift + R on Mac, control + F5 on Windows). This clears the cache, which may be displaying a previous version of the page.

Patches: Apply a Diff

Sometimes you want to add a specific bug fix without doing a full theme upgrade. You can do that via Tools > Apply Diff.

Use Case: Your Search experience is on Theme v1.22.0, the latest is v1.25.0, but Theme v1.22.1 includes a specific fix you need. You don't want to upgrade all the way to v1.25.0 - you can apply just that patch.

Note: Patch updates are not included in the changelog. Reach out to Yext if you need to resolve a bug without upgrading the entire theme.

Steps to Apply a Diff:

1. Check which version of the theme you are currently on in package.json.
2. Read through the instructions provided by Yext thoroughly, including upgrade implications, and note any actions needed before or after the patch.
3. Make any changes needed before applying the patch (e.g., overriding standard cards you want to keep as-is).

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

   

5. Enter the URL of the diff file or upload a diff file. Click View to preview the changes, then Apply to apply them.

   

6. Make any changes needed after the diff is applied (re-forking certain files, following configuration instructions).
7. Test Live Preview thoroughly.
8. Commit your changes, publish to Production, and do some light testing.

Rebuild Your Site

Use this approach when upgrading from a legacy theme version (v1.10 or earlier), or any time the upgrade process would be more work than starting fresh. This process retains the domain and Yext Pages site currently in use and will not break your live site.

1. Navigate to Pages > [site to rebuild] and click View Code Editor.
2. Hover over the master branch, click the three dots, and click Create new branch.
3. Enter a descriptive branch name such as rebuild-theme-1.33.
4. Select the Search Jambo Template for the new branch. This creates a fresh branch using the latest theme template.
5. Click Create Branch.
6. Re-add each page and card of the Search experience, including any styling or customizations.
7. QA the experience thoroughly using Live Preview and the staging site.
8. Once everything looks good, merge the branch into master:
   1. Navigate to Pages > [site to rebuild] and click View Code Editor.
   2. Hover over your working branch, click the three dots, and click Merge branch.
   3. Select master, then click Merge Branch.
9. Push the update to the live site.

The Search experience will still live in the same Pages site and domain - no changes are needed for the integration or from your client.