Service manifest

Every service comes with a manifest.json file providing metadata. Typically amanifest should at least specify the version of ArangoDB the service supports andthe main JavaScript file which Foxx will use as the entrypoint to your service:

  1. {
  2.   "engines": {
  3.     "arangodb": "^3.4.0"
  4.   },
  5.   "main": "index.js"
  6. }

Tooling integration

If you are using an IDE or editor that supports JSON schema for code intelligenceor validation, you can use the public Foxx manifest schemaavailable at the third-party JSON Schema Storeby adding a $schema field to your manifest.json file:

  1. {
  2.   "$schema": "http://json.schemastore.org/foxx-manifest"
  3. }

Visual Studio Code

In Visual Studio Code you can also enable theFoxx manifest schema for all manifest.json files by adding the following to youruser or workspace settings:

  1. {
  2.   "json.schemas": [
  3.     {
  4.       "fileMatch": [
  5.         "manifest.json"
  6.       ],
  7.       "url": "http://json.schemastore.org/foxx-manifest"
  8.     }
  9.   ]
  10. }

Structure

The following fields are allowed in manifests:

The JSON schema. See above.

  • 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 redirectto 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 longerdefaults to "index.html".

  • dependencies: Object (optional)

An object mapping local aliases to dependency definitions.Each entry can be a dependency name and version range in the formatname:version or an object with the following properties:

  • name: string (Default: "*")

Name of the dependency.

  • version: string (Default: "*")

Version range of the dependency.

  • description: string (optional)

Human-readable description of the dependency or how the dependency is used.

  • required: boolean (Default: true)

Whether the service requires the dependency to be assigned in order to function.If a required dependency is not assigned, the service will marked asinoperable until a service mount point has been assigned for the dependency.

  • multiple: boolean (Default: false)

Whether the dependency can be specified multiple times. If a dependency ismarked as multiple, the value of the local alias will be an array of allservices assigned for the dependency.

See the dependencies guide for more information.

  • engines: Object (optional)

An object indicating the semantic version ranges ofArangoDB (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 servicehas been tested against. Foxx maintains a strict semantic versioning policyas 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 below4.0.0) for maximum compatibility.

  • files: Object (optional)

An object defining file assets served by this service.

Each entry can represent either a single file or a directory.When serving entire directories, the key acts as a prefix and requests tothat prefix will be resolved within the given directory:

  • path: string

The relative path of the file or folder within the service.

  • type: string (optional)

The MIME content type of the file. Defaults to an intelligent guess basedon the filename’s extension.

  • gzip: boolean (Default: false)

If set to true the file will be served with gzip-encoding if supportedby the client. This can be useful when serving text files like client-sideJavaScript, CSS or HTML.

If a string is provided instead of an object, it will be interpreted as the path option.

Example serving the public folder at /static and the favicon.ico at /favicon.ico:

  1. "files": {
  2.   "favicon.ico": {
  3.     "path": "public/favicon.ico",
  4.     "gzip": false
  5.   },
  6.   "static": "public"
  7. }
  • 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 JavaScriptpaths 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 whenthe service is mounted or started.

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

  • provides: Object (optional)

An object mapping dependency names to version ranges of that dependencyprovided by this service. See the dependencies guidefor more information.

  • scripts: Object (optional)

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

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

One or more patterns to match the paths of test files, e.g.:

  1. "tests": [
  2.   "**/test_*.js",
  3.   "**/*_test.js"
  4. ]

These patterns can be either relative file paths or “globstar” patterns where

  • * matches zero or more characters in a filename
  • ** matches zero or more nested directories.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 theservice 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, ideallyin 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 ASCIIhyphen (-) and underscore (_) characters. The name must not start witha 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 theweb interface. This should be a JPEG or PNG image that looks good at sizes50x50 and 160x160.

  • version: string (optional)

The version number of the Foxx service. The version number must follow thesemantic 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. }