home shape

Reusable Foxx Apps with Configurations: ArangoDB Development

While the optional configuration field in Foxx manifests had experimental support all the way back to ArangoDB 2.1, the feature was previously undocumented and not well understood. The upcoming ArangoDB 2.6 release officially introduces Foxx configurations, allowing you to make your existing Foxx apps more re-usable and to make better use of third-party apps.

Let’s say your Foxx app needs an API key to make a request to a third-party service using the request module introduced in ArangoDB 2.5. Without using configurations, your code might contain the hard-coded API key:

var request = require('org/arangodb/request');
var API_KEY = '4172616e67-6f44422072-6f636b7321';
// ...
controller.post('/bananas', function (req, res) {
 var response =
request.post('https://fruitbar.example.com/api/v2/bananas', {
   headers: {'x-api-key': API_KEY},
   json: req.json()
 // ...

This is obviously bad style. If the API key changes we need to update the source code and if we want to re-use the same app with a different API key we have to fork our code base. We also likely end up with credentials in our source control repository, which is a security nightmare.

Luckily we can now adjust our manifest to change that. Just at the following to the app’s manifest.json

 // ...
 "configuration": {
   "apiKey": {
     "description": "Example.com FruitBar API Key",
     "type": "string"

…and the configuration value becomes available in our Foxx app as a property of the applicationContext:

var API_KEY = applicationContext.configuration.apiKey;

Note that if you mount a Foxx app for the first time and the app has configuration fields that do not provide default values, you have to configure the app before it becomes active. You can adjust the configuration of your Foxx apps using the foxx-manager CLI from the shell, the web admin frontend in your browser or using the REST API.

If you want to give configurable Foxx apps a try, many of the apps in the Foxx app store already support configuration and can be used in ArangoDB 2.5. If you want to get the full experience, compile the development version of ArangoDB from Github.

Alan Plum avatar 1418721602 92x92

Alan Plum

Alan is an experienced web developer who feels equally at home in the backend and frontend. At ArangoDB he works on everything regarding JavaScript, with a special focus on Foxx.


  1. CoDEmanX on May 12, 2015 at 11:39 pm

    Very nice! Is there documentation yet in devel? My questions:
    1. How to specify a default value (attribute called “default”)?
    2. What is the “type” for? Is there some kind of auto-validation?
    3. Is nesting supported? Like this:
    {“configuration”: {“MyAPI”: {“keycode”: {“description”: “…”, “type”: “string”}}}}
    // appContext.configuration.MyAPI.keycode

    • Alan Plum on May 13, 2015 at 5:43 pm

      Yes, it’s documented in devel. See the chapter on the manifest file (“metainformation”).
      1. Yes, the attribute is called “default”.
      2. Yes, the type is validated when the configuration is modified.
      3. Currently nesting and object/array values are not supported. This may change in the future, but for now you can use type:string and parse the value yourself.

Leave a Comment

Get the latest tutorials, blog posts and news: