Live Preview | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• What Live Preview is
• How it works under the hood
• How to use it

Overview

As you know, previewing your changes as you’re developing is critical to your efficiency and ultimately your success. It will make building much, much faster and easier. When you preview the changes, you are able to see what your code changes look like before you commit, so you can catch issues or experiment as you build.

Look how easy this is:

How Live Preview Works - Behind the Scenes

TLDR; The Quick Version

The Live Preview compiles the latest information in your Code Editor to show you what it would look like if you were to commit your code and publish your page in its current state. Imagine if you didn’t have a preview and you had to blindly make commits and then check to see how those changes looked on your live site. You’ll soon find that the Live Preview is your best friend while developing!

Want to know more about how this works under the hood? At your own risk…

The Longer, Much More Technical Version

Here’s a description with lots of technical jargon (written by a developer, can’t you tell?):

Live Preview is made possible by spooling up essentially a small private backend cloud server in our platform, which we’ll refer to as a ‘container’. When a new commit is made to the repository, the Yext CI system not only generates the output files needed to publish your website, but it creates a bespoke docker container image for that commit, which is later run when you request a preview.

Because an image is precompiled for each commit, it reduces significantly the amount of time needed to spool up the container for preview (down to around 10 seconds). If you attempt to request a preview before the build is complete, the code editor will wait for the CI system to finish making the preview docker image, which is why sometimes it takes longer to be ready. It is still worth clicking the “Create Preview” button in the code editor beforehand, however, as it will ensure that your build will have a higher priority in the event that there is a backup of build requests in the CI system.

As you are previewing your site, when you click the ‘update preview’ button, your staged changes are synched with the cloud container, which also kicks off any compilation steps needed to produce your final output files (just like the CI system does when making builds). The results of these steps are streamed back from the cloud container as the console logs. It’s almost like you are running the development toolchain and editing files on your own machine, but you don’t have to worry about having the correct system setup as you instead have your own private development space running in the cloud!

Congrats if you read this far! Can’t say we didn’t warn you. Don’t worry about the details, unless you’re curious. It’s only important that you understand the tldr version for now.

The Console

As you’re updating your preview, you can (and should!) view the Console in the Code Editor to see if there are any errors. You’ll want to make sure that the console says that the preview is ready before you try to refresh to see your latest changes. You can access the Console by clicking on Tools > Console. This won’t be selectable unless you’ve started the Live Preview process.

How to Use Live Preview

Using the Live Preview is easy!

View Live Preview

By the time you’ve navigated to the code editor, your preview is already there and ready to go! When you click into the code editor, we are spinning up a container for dynamic code editing and preview behind the scenes. All you need to do is click View Live Preview at the top of the code edtior to open your local site in a new tab in your browser.

As you’re making changes, we’ll automatically update your preview whenever you click out of the code editor. If you open up the Tools > Console, you’ll see a preview refresh start building immediately when you click out of code editing. If you refresh your preview tab while an update is in progress, you’ll see an error page – don’t be alarmed! Just wait for your preview update to complete and refresh the page.

Note

If you click “Create Preview” before an index.html file exists on your site, you will be redirected to a directory where you can choose which page you want to preview. Keep in mind that if you haven’t actually created any pages yet, you won’t see any HTML files to preview — there’s nothing to preview yet! You need to create at least one page for this to work.

You can also share your preview link with others or use the link to open up your changes in different browsers. Note that the preview link will expire after a few hours.

Session Management

When you open up the code editor, you are either starting a new session or resuming a session (you’ll see a small toast message if you are resuming a session). You can share your session with a teammate by copying the url with the session ID in it. Or, you can go to Tools > Terminate Session to terminate your session (recommended if you have made commits outside of the code editor that you need to retrieve). Your session will remain active for 4 hours and in “paused mode” for up to 2 days. After that, you will automatically start a new session.

This also means that if you leave the code editor or hard refresh the page, you don’t lose any of your work! You will still be in your session. If you want to truly restart, you’ll want to terminate your session and then navigate back into the code editor.

Restarting Live Preview

You’ll want to click “Restart Live Preview” after any time you’ve updated dependencies, like if you run a Theme Upgrade.

Common Issues

The Live Preview is one of the most powerful tools you have at your disposal as a Search Admin so we cannot emphasize enough how important it is to feel comfortable using it. Here are a few things that might happen and what you can do – don’t worry these are all expected! Some of the detail below won’t make sense until you’re more familiar with how Search works so don’t worry if you’re a little lost. If you’re having any issues using the live preview, we recommend referencing back here to troubleshoot.

Yext Logo or 404

If you see the Yext logo instead of your site, don’t panic! This just means that you refreshed the page while the preview was still rebuilding. Navigate back to the Code Editor and open up the console. You want to make sure you wait for the preview build to be finished. It should look like this when it’s ready for you to refresh:

Desktop/

If you see a file directory instead of a live site when you click Create Preview, this can mean a couple things:

1. You don’t have an index file. This could be intentional or it could be that you haven’t created it yet. If you have defined any other pages, you should be able to access your experience by clicking on any of the .html files.

2. You have an index file but you added it as a staged change. The initial preview is based off your original repo and doesn’t include any staged changes you’ve made in the browser. To incorporate those changes, just click “Update Preview”.

3. You have an index file and, if it was staged you updated the preview, and it’s still not working. This would indicate that there is a larger issue with your site. We would recommend making a trivial change to a file (e.g., you could add a space at the end of a line on a page in your config/ directory) and clicking “Update Preview”. Then, open up the console logs (Tools > Console) and look for any error messaging in the logs to identify the issue.

Search Bar Doesn’t Load

This is an issue with your code, and not the preview. It means that there is something blocking us from being able to initialize the search bar. For example, it might mean that you don’t have the experienceKey filled out yet or it’s invalid. If this happens, we recommend:

1. Check the required fields for your main files and make sure everything is provided

2. Try making a trivial change to a file (e.g., you could add a space at the end of a line on a page in your config/ directory) and click “Update Preview”. Then, open up the console logs (Tools > Console) and look for any error messaging in the logs to identify the issue.

“I love my changes, what do I do next?”

Once you feel good about your changes, you’re ready to commit them! We’ll cover that in the next unit.