🚀Get started

Let's start using boilerplate to make apps already!

Get up and running

1. Clone repository to the place of preference

git clone [e-mail]:OlegGulevskyy/zendesk-vite-boilerplate.git zendesk-app

2. Install packages in the repo

cd zendesk-app
yarn

3. Ensure you have zcli installed (link)

yarn global add @zendesk/zcli

4. Start applications

a) Start zcli server

yarn zcli:start

b) Start application

yarn my-main-app:start

OR

yarn non-server-app:start

You will always need to have 2 commands running, in order to use the boilerplate. Command from A) and B).

• a) - zcli server that will serve your application to Zendesk's iframe

• b) - Your actual web application

It does not matter in which order you start each server. You can even start them both separarely. Because each of these applications are intended to be used in different locations (ticket sidebar and user sidebar) they will not conflict with each other, and you can work with both of them at the same time.

Building

For demonstration purposes, let's assume you modified some stuff inside any of those 2 demo projects or both of them even, and now would like to build and proceed to uploading your application to the actual Zendesk instance.

Nothing more simpler:

yarn build

You will notifce following output:

Running @app/zendesk...
cwd: packages/zendesk
cmd: ENV=prod APPS='my-main-app non-server-app' yarn build
Building manifest for app:  my-main-app
Config:  {
 ...
}
Building manifest for app:  non-server-app
Config:  {
 ...
}
-----------
Skipping server side app: my-main-app
Server side apps should be deployed to a separate domain and not bundled with the app
Current production URL: https://frontend-production-bc15.up.railway.app
-----------
Building app: non-server-app
Output dir: /Users/oleggulevskyy/Documents/dev/zendesk-vite-boilerplate/dist/assets/non-server-app

Running @app/non-server-app...
cwd: packages/non-server-app
cmd: ADDON_TYPE=non-server-app yarn build --outDir /Users/oleggulevskyy/Documents/dev/zendesk-vite-boilerplate/dist/assets/non-server-app --base="./"
vite v5.1.4 building for production...
✓ 34 modules transformed.
...
✓ built in 360ms

What has happened is that your first application my-main-app was not actually built by the boilerplate itself, because it recognises that the project is a server side application. This is enirely up to you to build the application and deploy it somewhere. The easiest thing to do is to deploy it to Vercel.

However, it did trigger build of non-server-app and the entire React application was built.

The result of the build you can find in /dist folder, that now looks like this:

.
├── assets
│   ├── logo-small.png
│   ├── logo.png
│   ├── logo.svg
│   └── non-server-app
│       ├── assets
│       │   ├── index-DiwrgTda.css
│       │   ├── index-DmyYh-Yb.js
│       │   └── react-CHdo91hT.svg
│       ├── index.html
│       └── vite.svg
├── manifest.json
└── translations
    └── en.json

At this stage, your project is ready to be packaged and shipped to Zendesk.

Packaging

Packaging an application simply means zipping the /dist folder into a zip file with help of zcli tool we installed previously.

Boilerpalte has a helper command for this:

yarn zcli:package

Now, in your /dist folder, you will see folder /tmp appeared. There is a zip file with random numbers (it's a timestamp) in its name - this is a packaged application, ready to be published.

Uploading / publishing app

I will leave out the part on publishing the actual application, but I invite you to read about it more in article provided by Zendesk - Uploading and installing a private app.

Get in touch

If you have any questions or troubles, feel free to jump into Discord server where I am always reachable and other like-minded developers can help you out.