The Manifest File

In the manifest.json you define the components of your application. The content is a JSON object with the following attributes (not all attributes are required though):

• author: The author name
• configuration: Define your app’s configuration parameters.
• contributors: An array containing objects, each represents a contributor (with name and optional email)
• controllers: Map routes to FoxxControllers
• defaultDocument: The default document when the application’s root (/) is called (defaults to "index.html")
• dependencies: Map names to Foxx apps
• description: A short description of the application (Meta information)
• engines: Should be an object with arangodb set to the ArangoDB version your Foxx app is compatible with
• exports: Map names to Foxx exports
• files: Deliver files
• isSystem: Mark an application as a system application
• keywords: An array of keywords to help people find your Foxx app
• lib: Base path for all required modules
• license: Short form of the license (MIT, GPL…)
• name: Name of the application (Meta information)
• repository: An object with information about where you can find the repository: type and url
• scripts: An object with script names mapped to filenames, e.g. your app’s setup and teardown scripts
• tests: An array of names of files containing mocha tests for the Foxx app.
• thumbnail: Path to a thumbnail that represents the application (Meta information)
• version: Current version of the application (Meta information)

If you install an application using the Foxx manager or are using the development mode, your manifest will be checked for completeness and common errors. You should have a look at the server log files after changing a manifest file to get informed about potential errors in the manifest.

A more complete example for a Manifest file:

{
  "name": "my_website",
  "version": "1.2.1",
  "description": "My Website with a blog and a shop",
  "thumbnail": "images/website-logo.png",

  "engines": {
    "arangodb": "^2.7.0"
  },

  "configuration": {
    "currency": {
      "description": "Currency symbol to use for prices in the shop.",
      "default": "$",
      "type": "string"
    }
  },

  "controllers": {
    "/blog": "apps/blog.js",
    "/shop": "apps/shop.js"
  },

  "exports": "index.js",

  "lib": "lib",

  "files": {
    "/images": "images"
  },

  "scripts": {
    "setup": "scripts/setup.js",
    "teardown": "scripts/teardown.js",
    "some-maintenance-script": "scripts/prune-comments.js"
  },

  "tests": [
    "test/**",
    "test-*.js"
  ],

  "dependencies": {
    "sessions": "sessions@^1.0.0",
    "systemUsers": "users",
    "mailer": {
      "name": "mailer-postmark",
      "version": "*",
      "required": false
    }
  }
}

The setup and teardown scripts

You can provide a path to a JavaScript file that prepares ArangoDB for your application (or respectively removes it entirely). Use the setup script to create all collections your application needs and fill them with initial data if you want to. Use the teardown script to remove all collections you have created.

Note: the setup script is called on each request in the development mode. If your application needs to set up specific collections, you should always check in the setup script whether they are already there.

The teardown script is called when an application is uninstalled. It is good practice to drop any collections in the teardown script that the application used exclusively, but this is not enforced. Maybe there are reasons to keep application data even after removing an application. It’s up to you to decide what to do.

Mocha tests

You can provide test cases for your Foxx app using the mocha test framework and an assertion library like expect.js or chai (or even the built-in assert module).

The tests array lists the relative paths of all mocha tests of your Foxx app. In addition to regular paths, the array can also contain any patterns supported by the minimatch module, for example:

• glob matching: ./tests/*.js will match all JS files in the folder “tests”
• globstar matching: ./tests/** will match all files and subfolders of the folder “tests”
• brace expansion: ./tests/{a,b,c}.js will match the files “a.js”, “b.js” and “c.js”

For more information on the supported patterns see the minimatch documentation.

Configuration parameters

Foxx apps can define configuration parameters to make them more re-usable.

The configuration object maps names to configuration parameters:

• The key is the name under whicht the parameter will be available on your applicationContext.configuration object

• The value is a parameter definition.

The parameter definition can have the following properties:

• description: a human readable description of the parameter.
• type: the type of the configuration parameter. Default: "string".
• default: the default value of the configuration parameter.
• required: whether the parameter is required. Default: true

The type can be any of the following:

• integer or int: any finite integer number.
• boolean or bool: true or false.
• number: any finite decimal or integer number.
• string: any string value.
• json: any well-formed JSON value.
• password: like string but will be displayed as a masked input field in the web frontend.

If the configuration has parameters that do not specify a default value, you need to configure the app before it becomes active. In the meantime a fallback application will be mounted that responds to all requests with a HTTP 500 status code indicating a server-side error.

The configuration parameters of a mounted app can be adjusted from the admin frontend by clicking the Configuration button in the app details or using the configure command of the foxx-manager command-line utility.

Defining dependencies

Foxx apps can depend on other Foxx apps to be installed on the same server.

The dependencies object maps aliases to Foxx apps:

• The key is the name under which the dependency’s exports will be available on your applicationContext.dependencies object.

• The value is a dependency definition.

The dependency definition is an object with any of the following properties:

• name (optional): the name of the Foxx app this app depends on.
• version (Default: "*"): a semver version or version range of the Foxx app this app depends on.
• required (Default: true): whether the dependency is required for this app to be usable or not.

Alternatively the dependency definition can be a string using any of the following formats:

• * will allow using any app to be used to meet the dependency.
• sessions or sessions:* will match any app with the name sessions (such as the sessions app in the Foxx application store).
• sessions:1.0.0 will match the version 1.0.0 of any app with the name sessions.

Instead of using a specific version number, you can also use any expression supported by the semver module.

Currently the dependency definition names and versions are not enforced in ArangoDB but this may change in a future version.

If an app declares any required dependencies, you need to fulfill its dependencies before it becomes active. In the meantime a fallback application will be mounted that responds to all requests with a HTTP 500 status code indicating a server-side error.

The dependencies of a mounted app can be adjusted from the admin frontend by clicking the Dependencies button in the app details or using the set-dependencies command of the foxx-manager command-line utility.

For more information on dependencies see the chapter on Foxx Exports.

Defining controllers

Controllers can be defined as an object mapping routes to file names:

• The key is the route you want to mount at

• The value is the path to the JavaScript file containing the FoxxController you want to mount

You can add multiple controllers in one manifest this way.

If controllers is set to a string instead, it will be treated as the value with the key being implicitly set to "/" (i.e. the root of your app’s mount point).

In other words, the following:

{
  "controllers": "my-controllers.js"
}

is equivalent to this:

{
  "controllers": {
    "/": "my-controllers.js"
  }
}

The files

Deliver all files in a certain folder without modifying them. You can deliver text files as well as binaries:

"files": {
  "/images": "images"
}