In this recipe we're going to build a very simple app to record free text notes alongside Deskpro tickets. To keep this first example quite basic, we're going to store the notes using local storage.

Starting an App Project

The first step is to clone our app skeleton template repository and install the dependencies, setup Git, and check the barebones app in your browser.

The first step is to clone the template repository.

mkdir my-app
cd my-app
git clone git@github.com:DeskproApps/app-template-vite.git .
 copy

As you'll be using your own repository to maintain your app project, remove the existing .git directory and initialise the local repository again.

# inside my-app directory

rm -rf .git
git init
 copy

Next, install the app project dependencies. We recommend Yarn for package management.

pnpm install
 copy

After the project dependencies have been installed, it's time to check that the barebones app is working in your browser.

pnpm start
 copy

This will start the Vite development server, and provide you with a URL to visit.

Copy/paste the URL into your browser, and you should see the following:

Excellent, our barebones app is working!

Install a Development Version

When developing your app you'll need an instance of Deskpro running. Apps are developed in-place, so we'll need to build the initial version of our app. Once built, add the hasDevMode flag to our manifest so we can see realtime changes to our app whilst it's running inside Deskpro.

Open the app manifest.json file and add the hasDevModeFlag flag:

{
  "name": "my-app",
  "title": "My App",
  "description": "My Deskpro app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": false,
	
  "hasDevMode": true,
	
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
  }],
  "settings": {
    "example": {
      "title": "Example Setting",
      "description": "Example backend only setting",
      "type": "string",
      "isRequired": false,
      "isBackendOnly": true
    }
  },
  "proxy": {
    "whitelist": [{
      "url": "https://example.com/.*",
      "methods": ["GET", "POST", "PUT"],
      "timeout": 10
    }]
  }
}
 copy

Next, we'll need to build and package our app so we can install it in Deskpro.

pnpm build:package
 copy

We should now have an app package located in ./build.

Now we need to upload this archive to Deskpro by navigating to Admin > Apps & Integrations > Apps > Available (tab) and clicking the "Upload App" button. Select the my-app.zip archive from your local computer and your app will be uploaded.

Once uploaded, click on the app under the "Available" tab to open it's drawer. Navigate to the "Settings" tab in the app drawer and click the "Install" button at the bottom.

Your app will now appear under the "Installed" tab.

Start your app development server again.

pnpm start
 copy

Click on the installed app to open it's drawer, then navigate to the "Developers" tab. Enable developer mode, and enter the dev server URL for "ticket_sidebar" target and click "Save".

Now refresh Deskpro in your browser and open a ticket. You should see that your app appears in the ticket sidebar like this:

Excellent! Our app is now running in dev mode within Deskpro. Open up the src/pages/Main.tsx component of your app and change the text inside the button - you should see your changes happen in real time.

Notes App UI

Ok, let's add a simple UI for our notes app. It consists of a text area where notes are displayed and updated, and a "save" button to persist the notes to local storage.

Open up the Main.tsx page and add the following components:

// src/pages/Main.tsx

import { FC } from "react";
import { Button, Stack, TextArea } from "@deskpro/app-sdk";

export const Main: FC = () => {
  return (
    <Stack gap={4} vertical>
      <label>
        Notes
        <TextArea rows={4} />
      </label>
      <Button text="Save" />
    </Stack>
  );
};
 copy

Your app UI should now look something like this:

Persisting and Recalling Notes

Ok, now that we have our UI, it's time to add some functionality. Let's take the notes that are entered and store them in local storage. Also, we can recall our notes from local storage and set them as the value of our text area.

import { FC, useState } from "react";
import { Button, Stack, TextArea } from "@deskpro/app-sdk";

const storageKey = "deskpro/my-app/notes";

export const Main: FC = () => {
  const [notes, setNotes] = useState<string>(
    localStorage.getItem(storageKey) ?? ""
  );

  const save = () => {
    localStorage.setItem(storageKey, notes);
  };

  return (
    <Stack gap={4} vertical>
      <label>
        Notes
        <TextArea
          rows={4}
          onChange={(e) => setNotes(e.target.value)}
          value={notes}
        />
      </label>
      <Button text="Save" onClick={() => save()} />
    </Stack>
  );
};
 copy

Yay! We've successfully persisted and recalled notes from local storage in our app!

Of course storing notes in local storage isn't ideal - they may be lost when the user clears their browser cache and nobody can see them except for the author.

We can do better! In the next how-to guide we'll use app state to store our notes.