Packaging and Distributing Apps

Applicable Versions:

This page is valid for version 0.13.0 and above.

Packaging your apps empower other users to install and run them on their own Dropserver instance with minimal effort. A package contains an archive of the application files and assets, and a manifest describing the app.

Prepare Your App

While an app may run fine in ds-dev or even ds-host, it may need a little more polish before distributing it to a broader audience.

Developers should follow the guidelines for building an app.

Note that the backend code might import code from deno.land/x and possibly other sources. This is acceptable. The ds-host instance will fetch and cache these dependencies as necessary.

Some nice things to include in your app before packaging:

See the app manifest reference for specific details on each.

Changelog file format

The changelog is a plain text file that describes changes in the app for the benefit of the end-user.

The changes for a given version are preceded by a line containing the version being described. This version must match exactly the version in the app manifest.

Multiple versions can be described in the changelog file, in any order. See example below:


Removed all the explosions. Sorry about that.


Major release! Explosive new features!

Multiple lines of explosive new features in this release!!


Initial release.

Create an App Package

Make sure all built assets get built before running the app packaging tool.

To actually create an app package you must have ds-dev installed. Run the following command:

ds-dev -app=/path/to/app -create-package=/path/to/dist -package-name=my-super-app

Note that the app directory is not necessarily the root of your code repository. See the section on directory structure in building and app.

The directory passed to -create-package is where the package file and manifest will be written.

The -package-name is the base file name of the package. ds-dev will append the version (as specified in the manifest) and the tar.gz extension. In this case: my-super-app-0.1.0.tar.gz.

ds-dev will also output a complete manifest alongside the package with extension .json, as well as a .txt changelog file containing the changes for just the current version, and an app icon. These files get used by the application distribution website generation process (see below).

Use your packaged app

Once a package is created you can use it via ds-dev:

ds-dev -app=my-super-app-0.1.0.tar.gz

Upload the packaged app to your ds-host instance via the user interface. You can then create appspaces for this app. If you don’t have a ds-host instance, you can spin one up temporarily via Docker.

Distribute Your App

Distributing your app means making it very easy to install for other users. In Dropserver a user can install an app by pasting a URL that points to a special JSON file called an “app listing” that contains the list of available versions of an app.

ds-dev can generate this “app listing” just by looking at a directory of packaged apps. to generate the listing run:

$ ds-dev -create-listing=/path/to/packages/dir/

This creates app-listing.json and an index.html files alongside the package files. The listing looks like this:

  "versions": {
    "0.6.1": {
      "manifest": "my-super-app-0.6.1.json",
      "package": "my-super-app-0.6.1.tar.gz"
    "0.6.2": {
      "manifest": "my-super-app-0.6.2.json",
      "package": "my-super-app-0.6.2.tar.gz",
      "changelog": "my-super-app-0.6.2-changes.txt",
      "icon": "my-super-app-icon-4226f914.png"

Each value of package manifest changelog and icon are paths.

The HTML file is a minimal self-contained web page that echoes some of the information about your app for human consumption. It also includes the listing URL and invites users to install your app in their own Dropserver instance.

The generated files are intended to be served together. Simply upload the whole directory to a static host and you’re good to go.


Dropserver will not follow redirects when fetching the app listing and other files from your website. Also, it will only fetch app listings and app files over HTTPS.

Release a new version of your app

Thanks to the “app-listing” users will be able to install the latest version of your app soon after you publish. To ensure this process works well please ensure the following:

Dropserver instances that have your app installed from this URL will eventually pick up on the new version and suggest its installation to your users.

Move your published app to a new URL

If you move the published site to a new address, users who installed your app using the previous address will no longer get updates. To give these users a better experience, let them know what the new address is. You can do this in one of two ways:

    "new-url": "https://<the new URL for your app>"

In both cases the new URL should point to the new URL for app-listing.json.

With either of these changes Dropserver will invite users to update the link for the app.

What Next?