Migrating to v2

Zendesk Apps Tools (ZAT) provides a command to assist with migrating your v1 app structure to a v2-compatible app.

For information on how to run the command using ZAT, see Zendesk Apps Tools migrate.

If you would like to perform the steps manually, see the instructions below.

Manual migration

The first step to migrate your legacy app to the Zendesk App Framework (ZAF) v2 is to clone, fork or download the App Scaffold. This scaffold contains a very simple example app and includes build tools to support some features provided by ZAF v1, such as jQuery, Bootstrap 2.3, Handlebars and Underscore. It also includes a library of shims for some legacy v1 functions, such as renderTemplate, switchTo, setting and I18n.t. The App Scaffold also serves as an adaptor for your legacy app, so that your events and requests definitions can be translated to work with ZAF SDK v2.

Note: While ZAF v2 aims to support all existing framework features, in some cases some features may be missing or incomplete due to the nature of the new architecture. For more information, see our feature parity status page.

How does it work?

ZAF v1 has a strict folder structure and very limited support for external libraries and modules. In contrast, ZAF v2 allows you to structure your files and folders however you like. You're also free to include external libraries and third-party modules. To make this possible, ZAF v2 delegates some responsibilities to you. For example, the App Scaffold uses webpack to compile Handlebars templates, SCSS stylesheets, and CommonJS modules. You're free to use other technologies, but you may need to re-configure the build process yourself.

Using a Content Delivery Network (CDN)

Consider including popular JavaScript libraries from a CDN rather than including them in your app. The following example from the App Scaffold gets libraries from the jsdelivr CDN:

<script src="https://cdn.jsdelivr.net/g/lodash@4.3.0,handlebarsjs@4.0.5,jquery@2.2.0,momentjs@2.9.0,bootstrap@2.3.2"></script>

In the example, a jsdelivr feature creates a single file containing the specific versions of all the libraries. You can learn more about the feature in the jsdelivr docs.

Using the Zendesk Garden CSS

While ZAF v1 provided a set of base styles as well as Bootstrap 2.3 by default, ZAF v2 leaves the styling of your app up to you.

Zendesk Garden is designed to be a common baseline of styles and components between all Zendesk products. If you'd like your app to fit in with the rest of the Zendesk product branding, we recommend you include a link to the Zendesk Garden stylesheet in your app's HTML template:

<link rel="stylesheet" href="https://assets.zendesk.com/apps/sdk-assets/css/1/zendesk_garden.css" type="text/css">

Further information about the CSS classes in Zendesk Garden is available from garden.zendesk.com or the demo app.

Note: Including both Zendesk Garden and Bootstrap may conflict and result in unintended results. Zendesk Garden is not intended to be a complete replacement for all possible styles in Bootstrap. You may have to make significant structural changes to your app layout or add custom styles to fill in the gaps.

Folder structure

For more information about the App Scaffold's folder structure, see zendesk/app_scaffold#getting-started on Github.

Getting started

The following sections explain the steps to migrate your existing app to work with the App Scaffold.

  1. Clone, fork, or download the App Scaffold repo.
  2. Switch to the App Scaffold folder.
  3. Run npm install.
Running locally

To run your app locally in Zendesk Support, you need the Zendesk Apps Tools (ZAT).

After installing ZAT, you typically need two separate command-line interface tabs to develop an app locally. Use the first tab to run the zat server --path=./dist command to start the local web server. Use the second tab to run the webpack --watch command to build the project whenever you change the files.

Migrating your templates

Copy your existing app's templates into src/templates. Example:

  • cd app_scaffold
  • cp ../legacy_app/templates/* src/templates/
Migrating your translations

Copy your existing app's translations into src/translations. Example:

  • cd app_scaffold
  • cp ../legacy_app/translations/* src/translations/
Migrating your app.css

Copy your app.css into src/stylesheets with a new name and import it into app.scss. Example:

  • cd app_scaffold
  • cp ../legacy_app/app.css src/stylesheets/common.scss
  • echo "@import './common.scss';" >> src/stylesheets/app.scss
Migrating your app.js

Copy your app.js to src/javascripts with a new name and update its structure. Example:

  • cd app_scaffold
  • cp ../legacy_app/app.js src/javascripts/legacy_app.js
Updating the structure

Because your app is now compiled by webpack, you need to update its structure. Rather than returning the app object from an anonymous function, you export it using ES2015 syntax.


(function() {

  return {
    events: {
      'app.created': function() {



import BaseApp from 'base_app'; // ZAF v1 shims

var App = {
  events: {
    'app.created': function() {

export default BaseApp.extend(App);
Copying your manifest.json

You will need to copy across your existing manifest file and update it to be compatible with ZAF v2:

  1. Copy your legacy app's manifest.json to dist/manifest.json
  2. Update your locations as per the section below
  3. Update frameworkVersion property to 2.0.
Updating locations

In ZAF v2, your locations object needs to define URLs that point to HTML files. When migrating, you can point all your locations to the same HTML.


  "location": ["ticket_sidebar", "new_ticket_sidebar"]


  "location": {
    "support": {
      "ticket_sidebar":     "assets/index.html",
      "new_ticket_sidebar": "assets/index.html"
Now what?

Even after following these steps, your app might still not work unless you update your code to use the new ZAF SDK v2 APIs. See the ZAF Client API doc for examples on how the new APIs work. Additionally, you may need to rewrite some functionality that may be missing from the App Scaffold or simply may not be present in ZAF v2. In any case, this guide should give you a good starting point to get your app ready for the future. If you get stuck, don't hesitate to ask for help. You can reach us at support@zendesk.com.