Manifest files

Every service comes with a manifest.json file providing metadata. The following fields are allowed in manifests:

  • configuration: Object (optional)

An object defining the configuration options this service requires.

  • defaultDocument: string (optional)

If specified, the / (root) route of the service will automatically redirect to the given relative path, e.g.:

  1. "defaultDocument": "index.html"

This would have the same effect as creating the following route in JavaScript:

  1. const createRouter = require('@arangodb/foxx/router');
  2. const indexRouter = createRouter();
  3. indexRouter.all('/', function (req, res) {
  4.   res.redirect('index.html');
  5. });
  6. module.context.use(indexRouter);

Note: As of 3.0.0 this field can safely be omitted; the value no longer defaults to "index.html".

  • dependencies: Object (optional) and provides: Object (optional)

Objects specifying other services this service has as dependencies and what dependencies it can provide to other services.

  • engines: Object (optional)

An object indicating the semantic version ranges of ArangoDB (or compatible environments) the service will be compatible with, e.g.:

  1. "engines": {
  2.   "arangodb": "^3.0.0"
  3. }

This should correctly indicate the minimum version of ArangoDB the service has been tested against. Foxx maintains a strict semantic versioning policy as of ArangoDB 3.0.0 so it is generally safe to use semver ranges (e.g. ^3.0.0 to match any version greater or equal to 3.0.0 and below 4.0.0) for maximum compatibility.

  • files: Object (optional)

An object defining file assets served by this service.

  • lib: string (Default: ".")

The relative path to the Foxx JavaScript files in the service, e.g.:

  1. "lib": "lib"

This would result in the main entry point (see below) and other JavaScript paths being resolved as relative to the lib folder inside the service folder.

  • main: string (optional)

The relative path to the main entry point of this service (relative to lib, see above), e.g.:

  1. "main": "index.js"

This would result in Foxx loading and executing the file index.js when the service is mounted or started.

Note: while it is technically possible to omit this field, you will likely want to provide an entry point to your service as this is the only way to expose HTTP routes or export a JavaScript API.

  • scripts: Object (optional)

An object defining named scripts provided by this service, which can either be used directly or as queued jobs by other services.

  • tests: string or Array<string> (optional)

A path or list of paths of JavaScript tests provided for this service.

Additionally manifests can provide the following metadata:

  • author: string (optional)

The full name of the author of the service (i.e. you). This will be shown in the web interface.

  • contributors: Array<string> (optional)

A list of names of people that have contributed to the development of the service in some way. This will be shown in the web interface.

  • description: string (optional)

A human-readable description of the service. This will be shown in the web interface.

  • keywords: Array<string> (optional)

A list of keywords that help categorize this service. This is used by the Foxx Store installers to organize services.

  • license: string (optional)

A string identifying the license under which the service is published, ideally in the form of an SPDX license identifier. This will be shown in the web interface.

  • name: string (optional)

The name of the Foxx service. Allowed characters are A-Z, 0-9, the ASCII hyphen (-) and underscore (_) characters. The name must not start with a number. This will be shown in the web interface.

  • thumbnail: string (optional)

The filename of a thumbnail that will be used alongside the service in the web interface. This should be a JPEG or PNG image that looks good at sizes 50x50 and 160x160.

  • version: string (optional)

The version number of the Foxx service. The version number must follow the semantic versioning format. This will be shown in the web interface.

Examples

  1. {
  2.   "name": "example-foxx-service",
  3.   "version": "3.0.0-dev",
  4.   "license": "MIT",
  5.   "description": "An example service with a relatively full-featured manifest.",
  6.   "thumbnail": "foxx-icon.png",
  7.   "keywords": ["demo", "service"],
  8.   "author": "ArangoDB GmbH",
  9.   "contributors": [
  10.     "Alan Plum <alan@arangodb.example>"
  11.   ],
  13.   "lib": "dist",
  14.   "main": "entry.js",
  15.   "defaultDocument": "welcome.html",
  16.   "engines": {
  17.     "arangodb": "^3.0.0"
  18.   },
  20.   "files": {
  21.     "welcome.html": "assets/index.html",
  22.     "hello.jpg": "assets/hello.jpg"
  23.     "world.jpg": {
  24.       "path": "assets/world.jpg",
  25.       "type": "image/jpeg",
  26.       "gzip": false
  27.     }
  28.   },
  30.   "tests": "dist/**.spec.js"
  31. }