Welcome to a better Code Editing Experience
We’ve made significant behind-the-scenes updates to our in-browser Code Editor! Rather than executing code in the browser, Yext now spins up a container in the cloud to execute your code in realtime. This comes with a large number of benefits:
- Live Preview loads faster
- Code Editor session management, which means you can resume your work even after closing your tab, or share a link to your session with a collaborator
- Support for more advanced features, like the new ‘Add Vertical’ Jambo command
- Apply “diffs” easily to your repo to make collaboration easier and avoid unnecessary Theme upgrades
- Better security
Impact to Live Preview and Load Time
To support this, you will see some changes in how you interact with the Code Editor:
- When you click into a branch, we will initialize the container immediately. This means it may take a few moments for your files to load if you are starting a new session (see info on sessions below).
- Once the Code Editor loads, your live preview will be available immediately. Just click the “View Live Preview” button to proceed. No more “Update Preview” either – as soon as you click your cursor out of the Code Editor, we will automatically start the “update preview” process for you behind the scenes. Open up the Tools > Console to follow along or debug, just like before.
- You’ll be able to access and use Live Preview faster and more seamlessly than before!
Session Management
When you open up the Code Editor, you are now either starting a new session or resuming a session. You’ll see a small toast 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 hour 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.
Apply Diffs
You now have the ability to apply “patches” to your directory easily via Tools > Apply Diffs. Here, you can insert a diff file, preview the changes, and apply to your repo. The most common use case for this will be to add patches to the Theme without having to upgrade the Theme entirely. You’ll need to do this when you upgrade to the new Code Editor if you’re on a Theme version before 1.17.0 to add the custom Theme commands to your Jambo Commands. It’s also a great way to share updates between your repos or share a cool update with a colleague. All you need is a .diff or .patch file stored in a publicly accessible URL.
Updated Jambo Commands
The updated Code Editor is now using the actual Jambo CLI commands, as well as some custom-built commands that are controlled in the Theme. This means that over time, theme upgrades may introduce more commands that will help you to build better search experiences, like the new Add Vertical command in Theme 1.20. We also previously weren’t surfacing all of the available built-in Jambo commands so you’ll see more options than before.
Here’s a definition of the commands that should be present and when to use them.
-
Add Card: Use this to fork a card from the theme and customize it. Use this if you want to modify a card from what’s in the Theme to modify layout or data mappings.
-
Add Direct Answers Card: Use this to fork a Direct Answers Card from the theme and customize it. Use this if you want to modify how we handle direct answers by Entity Type or Field Type (for field-value structured direct answers) or to modify the featured snippet card, like modifying the CTAs.
-
Add Page: Use this to add a page to your search experience. You’ll be prompted to pick a page layout from the theme, like
universal-standardorvertical-grid. You will need to manually add things like verticalKey and cardType once the file is created. -
Add Vertical: Use this to add as a faster way to add verticals by creating the page and setting the verticalKey and cardType all at once. Note: This is only available in CBD and once you’ve upgraded to the Theme 1.20 EA branch or used one of the Apply Diff urls in step 7 below.
-
Build Pages: Use this if you are developing locally to run Jambo Build. This should automatically be triggered when you change a relevant file if you are using the typical Jambo/Theme setup.
-
Extract Translations: Use this if you are adding translation strings to your site to easily extract the strings that need to be translated into a .pot file. You can then upload this file to your favorite translation SaaS (like Smartling) to produce the needed .po files that you can save to your repo’s translation directory. The command will analyze the usage of translated strings throughout your repo and save you some time!
-
Initialize Jambo: Use this if you are starting from a fully blank repo to add the scaffolding / core files Jambo needs for a Jambo Build to work. You’d want to follow with Import Theme to use the Answers Hitchhiker Theme.
-
Import Theme: Use this command with Initialize Jambo if you start from a fully blank repo in order to import the Answers Hitchhiker Theme.
-
Override Theme: Use this to override any of the files from the Theme. This will create a copy of the file(s) in your top level directory and update jambo.json to know that you are providing an override. This is commonly used to override things like component behavior in the page templates.
-
Upgrade Theme: Use this command to upgrade to the latest version of the theme. By default, it will upgrade to the master branch of the latest Theme version (recommended) but for more advanced users you can choose to upgrade (at your own risk) to a branch that is still under development, like the early-access branch during the early-access period (instructions here).
Instructions to start using the new Code Editor with your repositories
If you are on Theme version before v1.8, you will need to upgrade your Theme before you can use the new code editor. If you need assistance with this, please reach out to hitchhikers-support@yext.com.
With this transition, you will need to follow some steps for any existing repositories to start using this. Please follow the instructions below.
-
Turn on the “Spring '21: Code Editor Improvements (early access)” feature in Account Settings > Account Features.
-
Navigate to the Code Editor. We recommend creating a branch before you proceed.
-
Click on the pencil next to your new branch or the master branch (whichever you choose). Since this is now spinning up a fresh container you should expect this to take a few minutes, especially if it’s your first time turning it on or after you’ve recently made a commit.
-
Once loaded, take a moment to look around:
- View Live Preview - click this to immediately launch your live preview. No more needed to click Create Preview. No more “Update Preview”. As soon as you click out of the Code Editor (e.g., move your mouse out of cursor), we will automatically trigger an update.
- Restart preview - do this after you run a theme upgrade or make any changes to dependencies.
- Tools - like before you have a set of tools you can use. See above for more information about updated Jambo Commands, Session Management, and Applying Diffs.
-
Navigate to Tools > Jambo Commands.
-
For any repos with Jambo version before v.1.10.2, you’ll be prompted to Upgrade Jambo. Follow the instructions to apply the update to your repository. We recommend going ahead and doing this right away so you don’t have to worry about it later. You may see “Something went wrong. Please refresh the page and try again” – That’s okay, Simply continue following the instructions below by applying the correct patch for your jambo version and then terminating the session.
-
For any repos with Theme before v1.17.0, you’ll need to either Upgrade Theme to the latest OR Apply a Diff (recommended) to use any Theme specific Jambo commands, like Add Card. This is because the old Code Editor had these hardcoded and the new one surfaces the Jambo Commands dynamically, which is one of the really cool benefits of the new Code Editor. To do this:
-
To Apply a Diff, navigate to Tools > Apply Diff (again, this is the recommended fastest approach to start using commands if that is all you’re trying to do – if you need other features in the latest Theme then you can go ahead and upgrade). Enter in one of the URLs below (depending on your Theme version) and click “Apply”. Note: Do not click “View” as these patch files are not currently compatible with “View” and it will break the ability to apply the patch if you click that button first.
-
If you are on Theme v1.17-v1.19, you don’t really need to make a change - the Theme should have the right files to work, except that it may not properly update the jambo.json file when you shadow a card and it won’t include the new Add Vertical command. If you want either of these fixes, use this .patch link. Otherwise, see the debugging section for more info.
-
If you are on Theme v1.16, use this .patch link
-
If you are on Theme v1.11-v1.15, use this .patch link. Sites using these theme versions may need their node version updated and their ci/serve.sh script updated. Refer to the troubleshooting instructions below for the
Unexpected token {Error and the./ci/serve.sh: line 2: serve: not foundError. All of these changes including the jambo upgrade and the patches can be made in a single commit. -
If you are on Theme v.1.8 - v1.10, follow instructions for Theme v1.11-v1.15 and then follow the instructions below for the error
Error: Cannot find module '@babel/plugin-transform-object-assign'. -
If you are on Theme 1.7 or older, please do a Theme Upgrade in the old code editor before proceeding. If you’ve already turned on the new feature, you’ll need to turn the feature off in Account Settings, complete the theme upgrade, and then proceed. You can post in the Community or reach out to hitchhikers-support@yext.com if you need assistance with the upgrade.
-
-
Refresh the Page.
-
Navigate to Tools > Jambo Commands to check that you can see all of the relevant commands. If you don’t, try doing a hard refresh. Otherwise, proceed to the debugging section.
-
Commit your changes.
-
Go to Tools > Terminate Session and terminate your session.
Now you should be good to go moving forward!
Debugging
There are a lot of changes here so here are some common debugging steps you might need to use.
Desktop/ files in staged changes
If you see a bunch desktop/ files in your staged changes when you load the code editor, don’t panic! All you need to do is navigate to your top-level .gitignore file and add “desktop/”. Once you click out of the code editor, you’ll see the files removed from staging. These are hidden because they’re the output files generated by Jambo.
Live Preview is Blank or returning Error
There are a few potential causes:
-
Check to make sure that your repo has the following in the config.json file in
ci_config.dependencies.required_filesobject:"dependencies": { "install_deps_cmd": "./ci/install_deps.sh", "required_files": [ "package.json", "package-lock.json", "ci/install_deps.sh" ]Example of Config File missing required_files
Example of Config File with corrected required_files
-
If that doesn’t fix it, make a trivial change (e.g., add a space to a file) and open up the Console logs to see if an error is printed. If so, follow any instructions there to resolve.
-
If you’re still stuck, post on the Community.
You don’t see all of the Jambo Command options
Review steps 6-8 in the instructions above. If that doesn’t resolve it, let us know by posting in the Community.
You are having an issue shadowing a card or direct answer card after moving over
Check your jambo.json file and make sure that the partials object contains “cards”, like this:
“Unexpected token {
This error can occur in the CBD console, and it likely means that the node version in the config is out of date. First, check if the node version is out of date and by opening up the config.json file (It may be renamed to match the site name), and look for “base_image_tag”: “node-12.18” inside the ci_config.
If you don’t see it the node version specified, find this part of the code:
"ci_config": {
"build_setup_cmd": "./ci/build_setup.sh",
"build_cmd": "./ci/build.sh",
…
}
And add a “base_image_tag” property and specify the node version:
"ci_config": {
"base_image_tag": "node-12.18",
"build_setup_cmd": "./ci/build_setup.sh",
"build_cmd": "./ci/build.sh",
…
}
After updating the node version, terminate the session and re-open the editor for the changes to take effect.
This error can also occur on theme v1.16 if a “commands” folder is in the desktop folder. If this is the case, delete the “commands” folder and add “desktop/” to the .gitignore if it is not there already.
“./ci/serve.sh: line 2: serve: not found” Error
This can occur after updating the node version. To fix it, update ci/serve.sh to use npx.
Example before:
#!/bin/sh
serve -l 8080 desktop/ &
grunt watch
Example after:
#!/bin/sh
npx serve -l 8080 desktop/ &
grunt watch
Then click “Restart Live Preview”
Error: Cannot find module ‘@babel/plugin-transform-object-assign’
This occurs on themes 1.10 and older. Inside package.json, find the following:
"devDependencies": {
"@babel/core": "^7.9.6",
"@babel/plugin-transform-runtime": "^7.9.6",
"@babel/preset-env": "^7.9.6",
"@babel/runtime-corejs3": "^7.9.6",
…
}
Update it so that it includes the following:
"devDependencies": {
"@babel/core": "^7.9.6",
"@babel/plugin-proposal-object-rest-spread": "^7.9.5",
"@babel/plugin-syntax-dynamic-import": "^7.2.0",
"@babel/plugin-transform-arrow-functions": "^7.8.3",
"@babel/plugin-transform-object-assign": "^7.10.4",
"@babel/plugin-transform-runtime": "^7.9.6",
"@babel/preset-env": "^7.9.6",
"@babel/runtime-corejs3": "^7.9.6",
Uncaught SyntaxError: Unexpected token ‘<’
This error can occur in the browser console of live preview while the live preview is still building. First, try waiting about 15 seconds and refreshing the live preview page. If that doesn’t work, try hitting the “Restart Live Preview” button in the code editor.