Your first app in 5 mins

Learn how to create your first app in just five minutes. This is a great introduction to the tooling around apps and the process to build and deploy your apps.

Prerequisites

Deskpro Apps are built using Javascript. You'll need to install NodeJS and NPM on your computer to build apps. Installers and binaries are available for every major operating system: https://nodejs.org/en/download/

You also need to install Yarn, which is the package manager we prefer. You can use npm for most things here, but we recommend yarn.

You will need to use NodeJS and Yarn from a console or command line interface. In the rest of this guide, we'll show you commands like this:

> yarn run start

• The > symbol represents the command prompt. Everything else after it is the command.

• node and yarn are expected to be installed into your path. If you used an automated installer, this should already be done.

• Finally, unless otherwise specified, your current working directory is expected to be the directory of your project (i.e. where your package.json file exist).

Create an app

The first step is to create your app using the special "create-react-app" script. This is done through the npx command (a sister-command to npm that downloads the installer and executes it all in one go).

> yarn create react-app hello-world --scripts-version @deskpro/apps-react-scripts

You can replace hello-world with whatever you want to name your app. It will create a directory on your hard-drive with that name.

Run the app

Your app is already a fully-functioning app. It's not doing anything very useful yet, but let's run it anyway:

> cd hello-world/
> yarn install
> yarn start
Starting the development server...
...
  Local:            http://localhost:31080/dev.html
...

Copy the local link to dev.html and open it up in your browser. This is your app running in the app developer environment. The dev environment uses mocked data (that you can even customise), it has hot-reloading and it shows enhanced error messages.

You can run your app in developer mode within your real helpdesk too -- refer to the page Running in dev preview for details on that. But for now, it's simpler and faster to use the local environment.

Here's what you'll see:

Edit your app

In your application directory, open the src/App.js file. This is the main ReactJS component for your app, and it's where you'll start adding your own code for your app.

The app by default is showing "your" name -- that is, the name of the logged-in agent who is running the app. In the dev test environment, this is a bogus "Joe Kool", but when deployed to a real helpdesk, it would be the actual agent.

Let's modify the code a bit to implement a real-world scenario. Let's take the email address of the user who started the ticket, and create a few buttons that link to an external system.

First, let's import a Button from the standard UI widget library. Just add it to the top after the other imports.

src/App.js

import { Button } from '@deskpro/apps-components';

Then, we need to load some data from Deskpro. We need to get the current context, which is an object that lets us fetch information related to where the app is being run. For example, in our case, we're making an app that runs in a ticket, so we use the context as a way to fetch information about the ticket.

This kind of logic belongs in the componentDidMount method. This is where ReactJS recommends you put this kind of loading code:

src/App.jsx

  componentDidMount() {
    // dpapp is injected into your App automatically.
    // It is the main interface between your app and Deskpro itself.
    const dpapp = this.props.dpapp;

    // Here you see we're accessing the context,
    // in this case we're getting ahold of the ticket context.
    const ticketContext = dpapp.context.get('ticket');

    // And from that, we can interact with the ticket in various
    // ways. In this case we're just loading up some info about the user
    ticketContext.get('person').then(person => this.setState({ person }));
  }

Finally, let's update the render function to show some buttons:

src/App.js

  render() {
    const person = this.state.person;

    if (!person) {
      return (<div>Loading...</div>);
    }

    const primaryEmail = person.emails[0];

    return (
      <div>
        <p>Find {person.name} in our other systems:</p>

        <p>
          <Button
            appearance="primary"
            onClick={() => window.open(`https://members.example.com/${primaryEmail}`)}
          >Find in members area</Button>
        </p>

        <p>
          <Button
            appearance="primary"
            onClick={() => window.open(`https://accounts.example.com/${primaryEmail}`)}
          >Find in accounts</Button>
        </p>
      </div>
    );
  }

See the whole file here.

You can also add a more friendly name for your app by editing your package.json. Find the deskpro key and change the title property.

package.json

{
  ...
  "deskpro": {
    "title": "My Amazing App"
    ...
  }
}

Now take a look at your app in the dev demo page:

Deploying your app

When you're ready, you can build your app by running the build command:

> yarn run build
...
Creating an optimized production build...
Compiled successfully.
...
build/app.zip ready with 1141644 total bytes

Find the build/app.zip file on your hard-drive. This is your actual app that you can now install into Deskpro at Admin > Apps > Upload App. Now open any ticket and your app appears in the sidebar.