You can export a theme's files from Guide and work on the files offline in your favorite editor. To avoid zipping and importing the files into Guide every time you want to preview your changes, you can preview each change locally in a web browser using the Zendesk apps tools (ZAT). To preview a change, you simply save the theme file in your desktop editor and refresh the page in the browser. Example:
ZAT is a collection of developer tools that includes Sinatra, a web server that runs locally on your computer. After starting the preview mode, the process runs in the background. See the command-line interface on the lower side of the image.
Topics covered in this article:
Setting up local theme preview
To set up local theme preview
- If not already done, enable API access in your Zendesk Support account by going to Admin > Channels > API.
- Install the Zendesk apps tools (ZAT).
See Installing and using the Zendesk apps tools in the Develop Help Center.
- If you previously installed ZAT to build Zendesk apps, make sure to update it by running the following command in your command-line interface:
$ gem update zendesk_apps_tools
To install and use ZAT, you'll need a command-line interface (CLI). In macOS, you can use Terminal in the Applications/Utilities folder. In Windows, you can use the command prompt or Powershell. If you're a Windows 10 user, you can install and use a Bash shell, a more developer-friendly CLI. See Setting up a Bash shell in Windows 10.
Starting local theme preview
You should start local theme preview before you start working on theme files on your computer.
To start local theme preview
- In your command line interface, navigate to the folder containing the exported and unzipped theme files.
Use the cd command (for change directory) to navigate to a child folder. Example:
$ cd guide_themes/newlook_themeTo back up one directory, use cd followed by a space and two periods. Example:
cd .. - Run the following command:
$ zat theme preview - At the prompts, enter your Zendesk Support subdomain, as well as the email and password you use to sign in to Zendesk Guide.
The subdomain and email are saved in a text file named .zat in the theme's folder so that you only need to enter your password the next time you start preview mode. If you make a mistake entering your username or password, delete the .zat file and start again. Note that files with leading periods are hidden in macOS by default. See Show Hidden Files in Mac OS X on the osxdaily.com website.
If you use single sign-on (SSO) to sign in to Guide (such as using Google or Microsoft credentials), you can sign in using an API token that you can get from the Support admin interface. See API token in the REST API docs. When prompted by ZAT to sign in, enter {your_email}/token for your user name, where "/token" is the actual string "/token". Use the actual API token for your password. Example:
Enter your username: jdoe@example.com/token Enter your password: e8Pvy0pvGzE8meUQxWgjIYkjrAfter successfully signing in, preview mode starts and runs in the background:
- Copy the "Ready" URL in the output and paste it in a browser.
In the example, the URL is https://nadosolutions.zendesk.com/hc/admin/local_preview/start.
An unformatted page loads after you sign in. Modern browsers have a security feature that blocks certain local files (known as mixed content) from loading in a page. You can disable the feature in Chrome and Firefox as described in the following step.
- In Chrome or Firefox, click the shield icon in the Address bar and agree to load an unsafe script (Chrome) or to disable protection on the page (Firefox). In Firefox, the shield icon is located on the left side of the Address bar.
Note: Safari has no option to disable protection. You must use Chrome or Firefox for previewing.The correctly formatted page should load automatically. You can start editing theme files in your editor and previewing changes locally in the browser.
Previewing changes
After starting the theme preview mode, you can work on your theme files in your favorite editor. Work iteratively to develop and test your theme. For example, make some changes to your JavaScript, save the changes, then refresh the browser page to test the changes.
To preview changes
- Save the edited file in your editor.
- Refresh the page in the browser.
When you're done for the day, you can stop preview mode using one of the following methods:
- Switch to your browser and click the "To exit, click here" link at the top of the previewed page.
- Switch to your command-line interface and press Control+C.
60 Comments
Hi,
Is anybody else here facing issue with zat theme preview recently? I am running zat theme preview and every time it is throwing parsing error:
Can anybody tell why it is throwing this error? I have tried using it in two different accounts other than mine too but with no luck.
Thanks
Hey @Trapta,
I haven't encountered this issue, but maybe you can try to switch the port you are using by providing a --port option. You can also try to switch off live reload by providing the --no-livereload option.
Let me know if it helps.
@trapta, were you ever able to fix this? I keep losing connection to the socket on every code change.
@Eduardo Alberto, in my case it was the Duck Duck go which was creating an issue. We marked the URL in the whitelist and that does the trick.
Thanks
Has anyone had any luck troubleshooting livereload constantly losing connection?
@Eduardo Alberto, what error you are getting exactly everytime you are losing connection? Can you post a screenshot of the error you are getting?
Thanks
@Trapta Here's a screeshot:
I've already tried using incognito, checked if ports were being used, if extensions could be impacting, etc.
@Eduardo, what is showing on your terminal?
@Eduardo & @Trapta - I'm constantly fighting the same issues. The errors Eduardo mentioned show in the browser console but nothing in terminal until stopping. Upon stopping I usually see some version of this:
I've checked for hung processes, checked for other services using the port, isolated browser extensions, gem updates, etc etc etc. The standard process when trying to troubleshoot similar types of issues. I don't understand why local development for Guide themes has to be so convoluted and herculean. Spinning up a local virtual server and developing against it is nothing new, yet, based on these and other comments across the support site, it seems to have been problematic in this case for quite some time. What is the solution here?
@Jen, have you tried updating your zat using zat update?
@Trapta - yup. Updated zat, updated all gems, yadda yadda yadda...in short, I believe I've followed all suggestions published here and elsewhere within the support site. It's so incredibly frustrating to have localhost lose connection every time after about 10 seconds. So I build, quickly navigate to the page where my most recent changes are, view those changes, then have to Ctrl+C and do it all over again for each and every change. Overly laborious for what should be standard development.
@Jen Culp I don't see Zendesk fixing this any time soon. just run zat theme preview --no-livereload and manually refresh the page. It's better than having to restart the server every time.
Thanks @Eduardo - I guess that's what I'll have to do :shrug:
Hey all!
Trapta brought this thread to my attention, and I'm chatting with our Developer Support team about it. We'll let you know if we have any insight to share on this.
Hello! Thanks for convenient tool.
Recently noticed, that the script.js file is not live to update. So, whenever I make a change in a script.js file
it is not being synced(uploaded in preview). Everything else works just fine.
What could be the problem?
What info should I provide for debugging?
Using:
macOS Mojave 10.14.3,
ruby 2.3.7p456
@Alexey Vorobyov, try hard reloading. script file gets cached resulting in showing older version of file instead of updated one with the changes.
Let me know if this solves your issue.
Team Diziana
Thank you @Trapta. It works today good actually with normal reload.
Did you change anything or it just universe makes magic? =)
Hello all, great feature! Just mentioning that for me on Windows 10 it works best with --no-livereload as well, without that flag the style seems to disappear once the page is reloaded.
I'm also noticing that some of the $assets references in my style.css seem to be resolved correctly while others arent - for example something like background-image: url("$assets-foundry_logo-svg"); works fine, but referencing our fonts like so doesn't work:
@font-face {font-family: "Avenir";
src: url("$assets-avenirnext-regular-08-ttf");
font-weight: 300;
font-style: normal; }
and gives me the following error:
Is this a known issue?
Is it possible to define some theme settings locally ? I think the theme is using the default settings from the manifest. I wanted to have by default my production settings (to be sure to not break it) but it seems that it will be required to have by default the local ones and to configure the production after.
Hey @Arnaud,
You can export the theme that you are currently using in production to get a theme package with the manifest.json file with the values currently in use.
yes but theme settings are locally different thus it means that I have to update them locally but never commit them in my Theme code (I'm using the GitHub integration). It's possible but a bit annoying
I see, that's unfortunately not possible at the moment, but good product feedback!
Hi there,
When trying to run `zat theme preview` I am getting the following errors:
dist $ zat theme preview
Generating Generating theme from local files
/Users/myusername/.asdf/installs/ruby/2.3.1/lib/ruby/gems/2.3.0/gems/zendesk_apps_tools-3.2.3/lib/zendesk_apps_tools/theming/common.rb:43:in `settings_hash': undefined method `flat_map' for nil:NilClass (NoMethodError)
If anyone has any suggestions please could you help, thanks
Hey y'all!
I'm also hitting the same error code. This is the first time I'm using zat theme preview. I ran zat new to initialize the zat app. I don't have a zat server running. Could someone advise?
Hey Keanan and Ursula,
That error is coming up because the manifest.json file in your theme is either missing the "settings" parameter, or that parameter is empty. Can you double-check that file and make sure you didn't accidentally delete all the settings from there?
Hi Anna,
Thanks for your response.
I was trying to use `zat` to setup a new project locally and then ran `zat theme preview` straight after, it was failing since this was a new fresh app without any settings.
I downloaded our current theme and ran `zat theme preview` which then worked.
Thanks
Howdy,
I'm trying to get a zat theme preview to automatically upload style changes created from an npm run watch command, but am running into problems. I believe the npm run watch script is causing zat to loose whatever FS connection is needs to register a change. I'm using laravel mix for css processing.
I can get both running in separate terminal windows, but as soon as the watch recompiles styles, zat will upload the changes, and then never register changes again. I have to restart the zat theme preview command.
Has anyone had any luck with a setup like this?
Hi Jason. Would you mind giving more details on your development setup? zat theme preview is run in the directory with the local Zendesk Guide Theme source. It picks up local theme changes, so they can be previewed without having to package up and upload the entire theme to your Guide instance. The Guide preview is done via a special URL that looks like https://your_subdomain.zendesk.com/hc/admin/local_preview/start
It sounds like you're also running Laravel with 'npm run watch' at the same time? I think a port conflict would show up in a different way, but if there is an issue with the 'zat theme preview' default port number, it can be changed with the '--port' option. Example:
zat theme preview --port 4444As you already requested, for any community members who have run such a combination, please join the conversation! Jason, if you have any additional details that you think may help, please include those as well.
Hey Bryan, thanks for getting back with me so quickly!
I am not running laravel, only "laravel mix" which is sort of a "gulp" build tool. Your ruby scss compiler works fine, but our development team has a lot of already produced tailwindcss components, and I needed to use the custom @apply directive.
I was able to get my setup working. If anyone is interested, I've wrapped a slimmed down version of the zendesk app inside an npm project.
.
├─ node_modules
├─ resources
| ├── js
| └── sass
├─ zat <-- This is the zendesk zat app
| ├── settings
| ├── templates
| ├── translations
| ├── .zat
| ├── manifest.json
| ├── script.js
| ├── style.css
| └── thumbnail.jpg
├─ .gitignore
├─ mix-manifest.json
├─ package.json
├─ postcss.config.js
├─ tailwind.js
├─ webpack.config.js
├─ webpack.mix.js
└─ yarn.lock
The ZAT folder has all the HBS templates, but the parent npm project has all the js and scss, which compiles to zat/script.js and zat/style.css respectively. This way I can have an npm watch on the root folder, and a zat theme preview on the ./zat folder, and neither will conflict.
```package.json
{
...,
scripts: {
"dev": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
"watch": "npm run dev -- --watch",
"zat": "zat theme preview --path=zat",
...
}
}
```
It's actually a pretty awesome dev cycle, about 4 seconds from "I change some scss files" to "The browser reflects those changes". And I can reuse a lot of our existing codebase.
Although if you're using tailwindcss like I am, you'll have to use purgeCss to get around the 300Kb style.css size limit, but only for production builds (development doesn't have a hard limit as far as I know, whoop whoop.)
Thank you for sharing all that detail Jason Horsley! Glad you got this working. It certainly sounds like a compelling approach for others to check out.
Please sign in to leave a comment.