Manifest Files

Manifest files are JSON files that FreeDOM uses to collect information about your app and the permissions it requires. At the core level, a manifest file looks like this:

    {
      "name": "My First App",
      "description": "This app is awesome"
      "app": {
        "script": "myScript.js"
      }
    }

There are optional parameters that can be specified but this is the bare-bones manifest that every app needs. A full list of possible options is listed below:

Manifest Options

name

(required) This specifies the name of the application to FreeDOM.

Example:

    "name": "Application Name"

description

(required) A description of the application you are writing.

Example:

    "description": "This is my app"

app

(required) This specifies the code for FreeDOM to run

Example:

    "app" {
      ...
    }

This option also requires the script sub-option described below.

script

(required) The Javascript file to load into the web worker (this path needs to be relative to the Main UI)

Example:

    "script": "path/to/script.js"

permissions

This specifies the permissions that the app requires. Here, any required modules should be specified. The example code below specifies an app that requires storage and identity permissions.

Example:

    "permissions": [
        "storage", "identity"
    ]

dependencies

This specifies any dependent apps that need to be loaded in order for the app to work properly. This allows for modularization of code. Dependencies are specified with the module to load, the URL where the manifest for the module, and the API to use to talk with the module if a specific API is needed.

Example:

    "dependencies": {
      "moduleName": {
        "url": "path/to/module.json",
        "api": "social"
      }
    }

Notice that the dependencies point to the manifest file and not the script itself.

constraints

This key is used to define module constraints, specifically on how this module handles its global namespace, and its ability to be stopped and resumed. The constraints dictionary currently has two keys, isolation and placement. Isolation can be one of always, app, or never, and defaults to always. This specifies that if the module is a dependant of multiple other modules, should they all be in separate global namespaces (always isolated), should all references within one app be merged together, or should all references to the module use a single namespace (never isolated). Placement specifies how tolerant the module is to being torn down and resumed. The three possible values are local, stable, and redundant, and the key defaults to local. When local the system will attempt to place the module as close to the code which interacts with it as possible, when stable is specified, the system will instead attempt to place it in a context where it can have as stable of a lifetime as possible. redundant may potentially instantiate the module in multiple runtimes to ensure that an instance is always running

Example:

    "constraints": {
      "isolation": "never",
      "placement": "local"
    }

API

The API key is used to export a custom API interface from this module that other modules can consume. The API dictionary maps an API name to its definition, using the same json specification language used by built in APIs. These definitions can be thought of as the specification of a class, with keys mapping to properties and methods, and their values defining the arguments and return values of those fields.

Example:

    "api": {
      "chat": {
        "send": {"type": "method", "value": ["string", "string"]},
        "recv-status": {"type": "event", "value": "string"},
      }
    }

This example defines the chat api, which has a method, send, which takes two arguments (in this case the destination and message). The API also specifies an event, recv-status, which may be emitted by the API, which will have a string value. Information on providing and consuming such an API are documented in the Provider and Client API sections, respectively.

Provides

The provides key allows the module to specify which APIs it wants to export. These may be either built in APIs, with well-known names, or custom APIs defined in the API key.

Example:

    "provides": ["chat"]

Default

The default key allows a module to specify how it wants to export its interface if no specific API is agreed upon between the consumer and producer. This is used in order to allow the root freedom.js module (the one included by a page) to export a custom API, and to allow developers to suggest the public-facing API for a module.

Example:

    "default": "chat"