Manifest (package.json)

Every app needs an app manifest (typically written into package.json). This page is a reference to the keys of the manifest.

Where to define the manifest

There are two places you can define the manifest. The first way is to create a separate manifest.json file at the root of your app. The second way is to add a deskpro key to your package.json file.

Both methods behave identically, and both have the same structure.

package.json

package.json

{
  "name": "hello-world",
  "version": "0.1.0",
  "private": true,
  "dependencies": { ... },
  "devDependencies": { ... },
  "scripts": { ... },
  ...
  "deskpro": {
    "version": "2.3.0",
    "title": "My Amazing App",
    "isSingle": true,
    "scope": "agent",
    "targets": [
      {
        "target": "ticket-sidebar",
        "url": "index.html"
      },
      {
        "target": "install",
        "url": "install.html"
      }
    ],
    "storage": [],
    "settings": [],
    "deskproApiTags": [],
    "externalApis": []
  }
}

manifest.json

manifest.json

{
  "version": "2.3.0",
  "title": "My Amazing App",
  "isSingle": true,
  "scope": "agent",
  "targets": [
    {
      "target": "ticket-sidebar",
      "url": "index.html"
    },
    {
      "target": "install",
      "url": "install.html"
    }
  ],
  "storage": [],
  "settings": [],
  "deskproApiTags": [],
  "externalApis": []
}

Relationship between apps and package.json

All apps require a package.json file because all apps use the apps SDK and the tools included in it (build tools, testing, mock data, etc). The library, tooling, and run scripts are managed via npm in package.json.

As described above, you may include the deskpro manifest information in package.json as well. This is just a convenience though, it behaves no differently versus just defining a separate manifest.json.

It has no special relationship with the app itself. For example, the name and version you set in package.json is completely separate from the name and version of the app you specify in the manifest.

So the summary is this: package.json is for developers. The manifest information is what the app itself uses.

Reference

title

Type: String, Default: none

This is the title of your app. It can be anything. This is what administrators will see when installing and configuring the app; and by default, this title that is displayed in the title bar of the app itself when rendered to the screen.

version

Type: String, Default: none

The version of your app as it appears to administrators. Your version should be a compatible semver version string. For example major.minor.patch like 2.3.4.

Only semver versions are supported. That means esoteric version names like MyApp Fast Badger Edition or v4 Golden Master are not valid versions.

isSingle

Type: Boolean, Default: true

This flag determines if the app can be installed multiple times or not. If it's plausible that administrators would want to install your app more than once, then you can set this to false to allow multiple instances.

This usually only makes sense if your app uses settings that change the behaviour of the app significantly. For example, the "Custom HTML" app allows the administrator to enter arbitrary templated HTML. Since the behaviour changes based on the HTML defined, you can see that it's possible the admin might want two different apps showing two different bits of HTML.

targets

Type: Array of target, Default: none

This is an array of locations in Deskpro where your app actually renders to. Each target is an object with two keys:

• target: String. The ID of the location.

• url: String. The path to the file in the app, relative to the public/ directory (e.g. index.html).

Refer to the targets reference for more information. <<TODO>>

storage

Type: Array of storageDef, Default: none

If your app needs to store any data, then this is an array that defines what data it is that you store, and how it should work. Each storageDef item:

• name: String. The unique name for the value you want to store.

• isBackendOnly: Boolean. Set to true to make sure the value is never exposed to the front-end. This is most useful for secrets that later might be used with the API proxy. <<TODO link to proxy>>

• permRead: String. Who can read the setting: EVERYBODY or OWNER.

• permWrite: String. Who can write the setting: EVERYBODY or OWNER.

For more information refer to the storage documentation. <<TODO link>>

settings

Type: Array of settingDef, Default: none.

If your app requires settings, such as API keys or other configuration, specify it here. The default installer will use these definitions to generate a setup form for the administrator during install.

<<TODO settings ref>>

For more information refer to the settings documentation. <<TODO link>>

deskproApiTags

Type: Array of String, Default: none.

If you want to allow the app to perform general Deskpro REST API calls, then this is a list of the API tags you want to allow.

For more information, refer to the documentation on using the REST API. <<TODO link>>

externalApis

Type: Array of String, Default: none.

If your app needs to use an external API through the API proxy, it must be white-listed here.

Refer to the documentation on using the API proxy. <<TODO link>>