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. This article focuses on the first two: upgrades to the Search UI SDK and Hitchhiker Theme.
| Search Component | Changelog | Where to Update |
|---|---|---|
| Search UI SDK | Search UI SDK Changelog | Frontend Code Editor — global_config.json file |
| Answers Hitchhiker Theme | Hitchhikers Theme Changelog | Frontend Code Editor — "Upgrade Theme" Jambo command |
| Speed Optimized Search Bar | Search UI SDK - Search Bar Only Changelog | Integration (done by owner of site where search bar lives) |
| Legacy Search Bar | Search UI SDK Changelog | Integration (done by owner of site where search bar lives) |
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 — meaning you'll need to update the SDK when upgrading the theme.
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. Occasionally, Yext may ask you to upgrade your search bar version if it's no longer supported or if there has been a major change (for example, a breaking bug in v0.13.0 of the search bar was fixed in v1.0.0).
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:
- Referencing the theme file and copying over new lines of code (only recommended for small changes where you know exactly what changed), or
- 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. To add new theme features to customized pages or cards created before a theme upgrade, you'll need to either override those files again or copy the new lines of code over.
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. You can then make any changes to this top-level file, but keep in mind you may need to account for later theme changes.
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.
For step-by-step instructions, follow the Theme Upgrade guide.
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 (for example, adding spacing between result cards). 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. For upgrades, carefully review the changes outlined in the changelog for each version release.