Use of this software is subject to important terms and conditions as set forth in the License file
This repo contains a scaffold to help developers build apps for Zendesk products.
- Clone or fork this repo
- Change (
cd) into theapp_scaffolddirectory - Run
npm install
To run your app locally in Zendesk, you need the Zendesk Apps Tools (ZAT).
You'll also need to run a couple of command-line Node.js-based tools that are installed using npm. For a node module to be available from the command-line, it must be installed globally.
To setup these and other dependencies, run these commands:
gem install zendesk_apps_tools
npm install --global webpack foreman karma-cli
Note: Foreman was originally created as a Ruby tool. If you prefer, you can install it by gem install foreman instead.
Note: The App Scaffold currently depends on zat v1.35.12 or greater.
Foreman allows you to easily run multiple processes in one tab. One process is zat server --path=./dist, which serves the app in a way that can be run in a supported Zendesk product. The second is webpack --watch to rebuild the project whenever you save changes to a source file.
To run these processes, run
nf start
or run the individual commands from the Procfile in separate terminals.
Note: If you installed the Ruby version of foreman, you'll need to use foreman start.
The App Scaffold includes many features to help you maintain and scale your app. Some of the features provided by the App Scaffold are listed below. However, you don't need prior experience in any of these to be able to use the scaffold successfully.
ECMAScript 6, also known as ECMAScript 2015, is the latest version of the ECMAScript standard. The App Scaffold includes the Babel compiler to transpile your code to ES5. This allows you to use ES6 features, such as classes, arrow functions and template strings even in browsers that haven't fully implemented these features.
- Handlebars templates
Handlebars is a powerful templating library that lets you build semantic templates for your app with minimal logic.
- SASS stylesheets
Sass is an extension of CSS that adds power and elegance to the basic language. It allows you to use variables, nested rules, mixins, inline imports, and more.
- Webpack module bundler
Webpack compiles web browser applications. It allows splitting your source code into modules and re-use them with require and import statements. It also allows splitting your compiled project into separate files that are loaded on demand.
- Karma test runner
The main goal for Karma is to bring a productive testing environment to developers with minimal configuration.
- Jasmine testing framework
Jasmine is a behavior-driven development framework for testing JavaScript code with a clean syntax.
The folder and file structure of the App Scaffold is as follows:
| Name | Description |
|---|---|
dist/ |
The folder in which webpack packages the built version of your app |
lib/ |
The folder in which the shims and files that make the scaffold work live |
spec/ |
The folder in which all of your test files live |
src/ |
The folder in which all of your source JavaScript, CSS, templates and translation files live |
.eslintrc |
Configuration file for JavaScript linting |
karma.conf.js |
Configuration file for the test runner |
package.json |
Configuration file for build dependencies |
webpack.config.js |
Configuration file that webpack uses to build your app |
The dist directory is the folder you will need to package when submitting your app to the marketplace. It is also the folder you will have to serve when using ZAT. It includes your app's manifest.json file, an assets folder with all your compiled JavaScript and CSS as well as HTML and images.
The lib directory is where the source code for the app shims and compatibility methods live. While you may modify or remove this code as required for your app, doing so is not recommended for beginners.
The spec directory is where all your tests and test helpers live. Tests are not required to submit/upload your app to Zendesk and your test files are not included in your app's package, however it is good practice to write tests to document functionality and prevent bugs.
The src directory is where your raw source code lives. The App Scaffold includes different directories for JavaScript, stylesheets, templates and translations. Most of your additions will be in here (and spec, of course!).
.eslintrc is a configuration file for ESLint. ESLint is a linting utility for JavaScript. For more information on how to configure ESLint, see Configuring ESLint.
karma.conf.js is a configuration file for Karma. Karma is a JavaScript test runner. This file defines where your source and test files live. For more information on how to use this file, see Karma - Configuration File.
package.json is a configuration file for NPM. NPM is a package manager for JavaScript. This file includes information about your project and its dependencies. For more information on how to configure this file, see package.json.
webpack.config.js is a configuration file for webpack. Webpack is a JavaScript module bundler. For more information about webpack and how to configure it, see What is webpack.
The App Scaffold's initialization code lives in src/index.js. For more information, see inline documentation.
The App Scaffold provides some classes under /lib to help building apps.
The I18n (internationalization) module provides a t method and Handlebars helper to look up translations based on a key. For more information, see Using the I18n module.
The Storage module provides helper methods to interact with localStorage. For more information, see Using the Storage module.
The View module provides methods to simplify rendering Handlebars templates located under the templates folder. For more information, see Using the View module.
The master branch of this repo contains modules and sample code to help you migrate from a v1 app. For detailed documentation on how to migrate from a v1 app, see our Migrating to v2 guide on the Zendesk Developer Portal.
If you're starting a v2 app from scratch you will need to check out the from-scratch branch:
git checkout from-scratch
npm install
The from-scratch branch uses up-to-date versions of the libraries included with the App Scaffold and also removes the shims needed when migrating from v1. It also includes sample code to help you get started on v2.
Another addition present only in the from-scratch branch, is the Zendesk Garden stylesheet. Zendesk Garden is designed to be a common baseline of styles and components between all Zendesk products. For more information, see Using the Zendesk Garden styles in the Zendesk Developer Portal.
If you want to see the exact differences between the master and from-scratch branches click here.
If you need to test your app with a parameters section in dist/manifest.json, foreman might crash with a message like:
Would have prompted for a value interactively, but zat is not listening to keyboard input.
To resolve this problem, set default values for parameters or create a settings.yml file in the root directory of your app scaffold-based project, and populate it with your parameter names and test values. For example, using a parameters section like:
{
"parameters": [
{
"name": "myParameter"
}
]
}create a settings.yml containing:
myParameter: 'some value!'If you prefer to manually input settings every time you run foreman, edit the Procfile to remove the --unattended option from the server command.
The App Scaffold is currently setup for testing with Jasmine (testing framework) and Karma (test runner). To run specs, run
karma start
Specs live under the spec directory and can be configured by editing the karma.conf.js file.
To check that your app will pass the server-side validation check, run
zat validate --path=./dist
If validation is successful, you can upload the app into your Zendesk account by running
zat create --path=dist
To update your app after it has been created in your account, run
zat update --path=dist
Or, to create a zip archive for manual upload, run
zat package --path=dist
taking note of the created filename.
For more information on the Zendesk Apps Tools please see the documentation.
External dependencies are defined in a module, lib/external_assets.js. The export of the module is imported into webpack.config.js at build-time. This ensures these dependencies are included on your app's index.html as well as in the test suite.
- Put up a PR into the master branch.
- CC and get a +1 from @zendesk/vegemite.
Submit Issues via GitHub or email support@zendesk.com.
Links to maintaining team, confluence pages, Datadog dashboard, Kibana logs, etc
- https://developer.zendesk.com/
- https://github.com/zendesk/zendesk_apps_tools
- https://webpack.github.io
Copyright 2016 Zendesk
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.