Server side app

A NextJS application for Navbar deployed to Vercel

In this article, we will go through a process of creating a brand new NextJS application for Navbar, that will be hosted on Vercel.

Create a webapp project

1. Creating NextJS project

cd packages/ && yarn create next-app

1. Let's give our project a name - this name does not affect much, but keep it simple and do not include special characters in there, as this name will be referenced in manifest.json file later automatically. I will call it super-cool-app

2. Choose whatever NextJS setup options you would like to use, those do not affect the boilerplate at all. I chose: - Yes to TypeScript (all the way) - No to ESLint - Yes to TailwindCSS - Yes to using /src directory - Yes to using App Router - No to customizing import alias

3. Install the packages required by NextJS

cd super-cool-app && yarn

Remember, these options selected in step 3 do not affect any boilerplate setup. Each project is a separate project and can have any technology it requires.

Alias scripts to manage NextJS project

You don't want to every time go inside /packages/super-cool-app to start the dev server. It is more convenient to do so from the root of your entire boilerplate, like 2 demo applications are showcasing. Let's do the same!

In the root folder of the boilerplate (attention, not our new NextJS project, but 2 levels up), open package.json file and add following to the scripts property:

"super-cool-app:start": "node scripts/run.mjs super-cool-app"

Here, the parameters of scripts/run.mjs receives a name of the package to be launched, which is a name of our newly created NextJS package.

While we are at it, let's also add a build script. Even though it is NOT required for server side apps, but I recommend keeping it for the sake of completeness, boilerplate will handle the rest for you.

Modify the build script to add the following:

"build": "node scripts/build.mjs prod super-cool-app"

Here, scripts/build.mjs receives an environment to build the app for (production a.k.a prod) and a name of the package. If you have multiple apps / packages, just list them here without commas.

Let's verify that everything works as expected! In the root directory, where we modified the package.json file, let's start up our NextJS package:

yarn super-cool-app:start

If everything was done correctly, you can see the following log:

Create a zaf.config.json file

Now, let's make this project recognisable by boilerplate, so that we can see it in our Zendesk instance.

In the root of your newly created project (I will refer to it as super-cool-app in my case), create zaf.config.json file.

cd packages/super-cool-app && touch zaf.config.json

Open it (or your entire boilerplate project) in your code editor (I use vim btw) and add the following content:

{
  "location": "nav_bar",
  "server_side": true,
  "production_url": "",
  "dev_url": "http://localhost",
  "dev_port": 3000,
  "size": {
    "height": 400
  }
}

You can learn more about what this file is in the section zaf.config.json of Configuration page.

We don't have a production url yet (our application is not deployed) but we already know, when we launch our NextJS project for local development, we use http://localhost as url and port 3000 (see screenshot from Alias scripts to manage NextJS project section).

If your NextJS project runs on a different url and port - update them in this file.

Last command to run, is to create a zcli server that will establish connection between our application and Zendesk:

yarn zcli:start

That's all it takes get a basic version of server side app running in your zendesk instance. Now, you can verify that everything works by visting your Zendesk ticketing instance, and do not forget to append ?zcli_apps=true to the end of the url.

Example: https://d3v5878-he.zendesk.com/agent/dashboard?zcli_apps=true

On the left side you will notice a small icon that is our application entry point:

Once opened, you should be greeted with default NextJS page.

Default NextJS running inside Navbar location in Zencesk ticketing system

Fan fact: your NextJS project (or any other server side apps) does not even need to be inside "packages" folder in its entirety. You can have it anywhere you want on your PC, but you do need to have a folder with whatever name in /packages directory that contains the very same zcli.config.json file we created earlier.

For sake of simplicity, I kept all egs in one baskket for this demo.

Add zafClient

We have our basic application, you are free to do whatever you want, but you will probably want to interact with Zendesk ZAF SDK (Zendesk Applications Framework).

To do so, we need to inject a script into the main page of NextJS. This step is slightly different than it is in bundled apps, because we don't use Vite as our bundler.

This step will be slightly different to each project based on a tech stack, I trust you knowing how to add scripts to your application (Nuxt, SvelteKit etc).

In our case of NextJS app, I will add this to src/page.tsx:

"use client";

import { useEffect, useState } from "react";
import Image from "next/image";
import Script from "next/script";

type ZafWindowClient = typeof window.ZAFClient;
type ZafClient = ReturnType<ZafWindowClient["init"]>;

export default function Home() {
  const [zafClient, setZafClient] = useState<ZafClient | null>(null);

  const handleClientLoaded = () => {
    if (typeof window !== "undefined") {
      const zaf = window.ZAFClient.init();
      setZafClient(zaf);
    }
  };

  useEffect(() => {
    if (zafClient) {
      zafClient.get("currentUser").then((data) => {
        console.log(data["currentUser"]);
      });
    }
  }, [zafClient]);

  return (
    <>
      <Script
        src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"
        onLoad={handleClientLoaded}
        onError={(e) => console.error(e)}
      />
    </>
      // ... Rest your application..
    )

zafClient types for additional typesafety

To get types autocomplte for zafClient (which will allow you to fetch data in a type-safe manner), adjust your tsconfig.json file with following properties:

  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    "../../node_modules/zendesk-types/**/*.d.ts" // Add type reference to existing zendesk package
  ]

And change moduleResolution to node:

"moduleResolution": "node"

That's it, if all done correctly, when opening NextJS application now, you can see in the browser log

Successfull zafClient execution

Types for zafClient are under a long construction, so some types maybe incorrect / not exhaustive.

Publish your application

Now, if you have Vercel account, use it - if not, go ahead and create one now.

I will not repeat Vercel's own documentation on how to deploy existing repositories, but what's important in the scope of this boilerplate, is that when this is done - take the production URL and insert it into zaf.config.json file:

  "production_url": "YOUR VERCEL URL"

Now, whenever you will use yarn build command, the output of /dist folder will point to vercel-deployed application, instead of your local dev environment (localhost).

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.