> For the complete documentation index, see [llms.txt](https://pineapps.gitbook.io/zendesk-applications-framework-boilerplate/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pineapps.gitbook.io/zendesk-applications-framework-boilerplate/create-your-own/server-side-app.md).

# 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

```bash
cd packages/ && yarn create next-app
```

2. 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`
3. 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`
4. Install the packages required by NextJS

```bash
cd super-cool-app && yarn
```

{% hint style="info" %}
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.
{% endhint %}

## 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:

<figure><img src="https://3788250611-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpvhBt6NDc3nQkORf1m5V%2Fuploads%2Fzc0QxpNuQSNnDWK3RrEe%2Fimage.png?alt=media&amp;token=4fea6fa0-874e-4793-ab93-32573e9887b6" alt=""><figcaption></figcaption></figure>

## 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.

```bash
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:

```json
{
  "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](https://pineapps.gitbook.io/zendesk-applications-framework-boilerplate/create-your-own/pages/b0U9Ka0lBD0ev198QHu2#zaf.config.json).

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](#alias-scripts-to-manage-nextjs-project "mention") 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:

```bash
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:

<figure><img src="https://3788250611-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpvhBt6NDc3nQkORf1m5V%2Fuploads%2F6ZvWjp3fGZolIVd1vdC9%2Fimage.png?alt=media&amp;token=66d80864-bbcb-4ae9-9897-2ab4956d3192" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://3788250611-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpvhBt6NDc3nQkORf1m5V%2Fuploads%2FhgilYIBbCoC0Jh9N4I1l%2Fimage.png?alt=media&amp;token=dc07277a-4c37-484f-a86a-7cfbe567892b" alt=""><figcaption><p>Default NextJS running inside Navbar location in Zencesk ticketing system</p></figcaption></figure>

{% hint style="info" %}
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.
{% endhint %}

## 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:`

```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

<figure><img src="https://3788250611-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpvhBt6NDc3nQkORf1m5V%2Fuploads%2FeiUrbgYB3jmoEnRopgN5%2Fimage.png?alt=media&amp;token=33557e2b-9dea-42e1-a63c-556537a6da82" alt=""><figcaption><p>Successfull zafClient execution</p></figcaption></figure>

{% hint style="info" %}
Types for zafClient are under a long construction, so some types maybe incorrect / not exhaustive.
{% endhint %}

## Publish your application

Now, if you have [Vercel](https://vercel.com/signup) account, use it - if not, go ahead and create one now.

I will not repeat [Vercel's own documentation](https://vercel.com/docs/deployments/git) 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](https://discord.gg/CGBW27FK7U) where I am always reachable and other like-minded developers can help you out.