Using ds-dev to Develop Dropserver Applications

ds-dev is a command line tool that runs Dropserver applications locally for the purpose of developing apps.

Some features and capabilities:

Installing ds-dev

Get the ds-dev executable from the Dropserver releases page. The packaged executable is available for MacOS or Linux. Windows users should use the Linux version under WSL2.


Dropserver uses Deno as its sandbox, therefore ds-dev requires Deno to be installed and available on the path.

Running A Dropserver App in ds-dev

To run an app you are developing in ds-dev you point it to the directory of the app’s source:

$ ds-dev -app=/path/to/app/dir/

Refer to the tutorial to learn what goes in the “app” directory.


Once ds-dev has started, you can leave it running while you work on your app code. It will reload the app when you save.

To provide an existing appspace as working data:

$ ds-dev -app=/path/to/app/dir/ -appspace=/path/to/appspace/files/

If you downloaded appspace data from ds-host you must unzip it before pointing ds-dev to it.


The appspace data is never modified. ds-dev copies all the files from the provided directory into a temporary directory, and uses that as the working data.

Run a packaged app

You can also run a packaged app in ds-dev. This can be handy if you want to take a quick look at an app that has already been packaged, or if you’d like to test a new version of an app locally:

$ ds-dev -app=/path/to/mysuperapp-1.2.3.tar.gz

ds-dev UI Basics

Once running ds-dev should indicate that its UI is available at http://localhost:3003/dropserver-dev/. Make sure this port is available prior to running ds-dev.

Open http://localhost:3003/dropserver-dev/ in a browser window. The UI should show you basic data about your app, and appspace if there is any.

If the app was loaded without errors and no migration is needed for the appspace data, then you should be able to visit http://localhost:3003/ to access your app’s ”/” page.

App Tab

The “App” tab shows you data that ds-dev collected about your app. In particular the name, version, schema and migrations available, along with a table of app routes.

ds-dev app tab user interface

If ds-dev encountered an error while trying to read this data it will report it at the top of this panel. Clicking “Expand” reveals the app log, which will help you figure out where the problem is.

Appspace Tab

The “Appspace” tab is mostly concerned with the data of this appspace (remember that an “app” is just code and an “appspace” is essentially a data directory for an instance of the app. See application model page.)

ds-dev appspace tab

The buttons at the top of this panel include:

At the bottom of this tab, as well as the “Users” and “Route Hits” tabs lives the appspace log. All console log statements as well as some internal messages related to the appspace are reported there.

Users Tab

Displays users and lets you select a user to emulate.

ds-dev users tab

If you loaded an existing appspace, the users in that appspace will show up there.


Users are considered appspace data. Therefore when you “Reload Appspace” in the “Appspace” tab, you reset the list of users.

Click on the radio button to select a user to emulate. Click “Log Out” to emulate no user (your requests are unauthenticated).

Route Hits Tab

Requests made towards your appspace show up under “Route Hits”.

ds-dev route hits tab

Each “hit” tells you what was requested (authentication if any, method, path) and the response code on the first line.

On the second line information about the matched route is shown: the authentication requirements, the route path, and the resulting action (serve static files or run function handler in sandbox).

Sandbox Control Widget

In addition to the four tabs we just outlined, an important feature is the sandbox control widget at the top of the ds-dev interface.

ds-dev sandbox control widget

You will see the status of the sandbox change as the system reloads app metadata, runs migrations, and executes route handlers.

Click the “Inspect” button to inspect running code. The process is as follows:

Create an App Package

To create a package that can be installed on ds-host from the app files run the following command:

$ ds-dev -app=/path/to/app/dir/ -create-package=/path/to/output/dir -package-name=my-super-app

-package-name is optional but highly recommended. Generated file names will start with “my-super-app” and will include the version specified in the manifest: my-super-app-1.2.3.tar.gz and my-super-app-1.2.3.json, etc…

-create-package generates the following files:

The package file can be installed manually on a Dropserver instance. The last three files are used when creating the distribution site.

Create an App Distribution Site

To create app distribution website files, run this command:

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

Where /path/to/packages/dir/ is the directory where you generated the package files.

Optional arguments are:

This command will generate app-listing.json alongside the package files. It contains a list of versions and the filenames for the package, manifest, changelog, and app icon. It also generates an HTML file that presents your application to a potential visitor, along with installation instructions.

After uploading all the files in /path/to/packages/dir/ to a static site server, any Dropserver user can install your app and keep it updated. See App Packaging and Distribution.

What Next?