Using an app manifest lets you manage your application's configuration declaratively as a manifest.json file.

The manifest represents your app's full configuration, including basic information like the name and description, OAuth configuration, feature details, and app endpoints.

You can export a manifest to reuse the app's configuration across versions, or import a manifest to get started from an example quickly.

Use cases

The manifest simplifies app management. Some things you can use it for:

Maintain consistent app setup across accounts or environments
Compare configuration between versions, and rollback to previous configuration
Integrate version-controlled manifests into automated pipelines for promotion and testing
Track who changed what and when, making it easier to understand and review changes

Prerequisites

This feature requires the monday apps CLI. Install the CLI to get started.

Get started

Export a manifest

This command exports a specific app's manifest. It will be saved as a JSON file in the current directory.

mapps manifest:export

Create a new app from manifest

mapps manifest:import --newApp

Or use the command with no flags to see all the other options:

mapps manifest:import

Import an app using Github action

We have a Github action to automatically create a new app version from a manifest file. Install the action here.

Install the latest CLI version

npm i @mondaycom/[email protected]

mapps init -t <YOUR_API_TOKEN>

Concepts

Manifest schema

The manifest schema establishes what data fields are needed for a valid app. Each manifest includes a version parameter that declares which schema version it uses.

Variable placeholders

You can inject data from your app's environment variables into the app manifest. Add the name of the environment variable in double curly braces, and we'll replace it with the corresponding environment variable. This is supported in CLI version @mondaycom/[email protected] and later.

{ 
  "app": { 
    "name": "{{MY_APP_NAME}}",
    "description": "This app automates tasks. Last updated: {{LAST_UPDATED_DATE}}"
  } 
}

Example manifest

{
  "version": "1.0.0",
  "app": {
    "name": "Manifest Tester App",
    "description": "Import and export app features with the app manifest. Documentation here - https://developer.monday.com/apps/docs/create-an-app-from-a-manifest-file",
    "color": "#1E7579",
    "oauth": {
      "redirectUri": [
        "https://myserver.com/oauth/callback2",
        "https://myserver.com/oauth/callback"
      ],
      "scopes": [
        "me:read",
        "boards:read"
      ]
    },
    "features": [
      {
        "key": "widget",
        "type": "AppFeatureDashboardWidget",
        "name": "Dashboard Widget - Quickstart React",
        "build": {
          "url": "https://abcdef123456.apps-tunnel.monday.app/",
          "kind": "url"
        },
        "data": {
          "boards": "with",
          "header": "without",
          "name": "Dashboard Widget - Quickstart React",
          "description": "A Quickstart web application build using ReactJS"
        }
      },
      {
        "key": "item-view",
        "type": "AppFeatureItemView",
        "name": "Item view - quickstart react",
        "build": {
          "url": "https://abcdef123456.apps-tunnel.monday.app/",
          "kind": "url"
        },
        "data": {
          "name": "Item view - quickstart react",
          "mode": "iframe",
          "query_parmas": true,
          "description": "A Quickstart web application build using ReactJS"
        }
      },
      {
        "key": "object",
        "type": "AppFeatureObject",
        "name": "Object feature - React",
        "build": {
          "url": "https://abcdef123456.apps-tunnel.monday.app/",
          "kind": "url"
        },
        "data": {
          "mode": "iframe",
          "query_parmas": true,
          "name": "Object feature - React",
          "uploading": false,
          "learnMoreLink": "https://abcdef123456.apps-tunnel.monday.app/learn-more"
        }
      },
      {
        "key": "doc-action",
        "type": "AppFeatureDocActions",
        "name": "Doc Actions - Quickstart App",
        "build": {
          "url": "https://abcdef123456.apps-tunnel.monday.app/",
          "kind": "url"
        },
        "data": {
          "mode": "iframe",
          "query_parmas": true,
          "modalSize": "medium",
          "supportedLocations": [
            "contextualToolbar",
            "addBlockMenu"
          ],
          "name": "Doc Actions - Quickstart App",
          "description": "A simple app to show how Doc Actions work",
          "uploading": false
        }
      },
      {
        "key": "board-view",
        "type": "AppFeatureBoardView",
        "name": "Board View feature",
        "build": {
          "url": "https://abcdef123456.apps-tunnel.monday.app/",
          "kind": "url"
        },
        "data": {
          "mode": "iframe",
          "query_parmas": true,
          "name": "Board View feature",
          "uploading": false,
          "feedbackLink": "",
          "description": " "
        }
      }
    ]
  }
}

Limitations

Please take account of the following limitations and edge cases:

The following features are unsupported: workspace templates and Integration for sentence builder. These features will not be included in any manifest exports. Uploading a manifest will not affect these features.
You can only export an app feature to JSON if it has a unique ID/feature slug.

Manifest schema

File

These top-level attributes are required in every manifest file.

Field	Description	Required
`version`	A string of the version of the schema that the file uses	Yes
`app`	An object with the configuration of the app	Yes

app

These attributes define the configuration & features of your app.

Field	Description	Required
`app.name`	A string of the name of your app	No
`app.description`	A string of the description of your app	No
`app.color`	A string of the hex code of the color of your app icon	No
`app.oauth`	The OAuth configuration of your app	No
`app.oauth.scopes`	A list of OAuth scope strings	No
`app.oauth.redirectUri`	A list of redirect URI strings	No
`app.features`	A list of feature objects; see `app.features` section below for schema definition	Yes

app.features

The app.features attribute contains a list of app feature configuration objects. Each feature object should follow this schema.

Field	Description	Required
`key`	A string of the unique key for this feature	Yes
`type`	A string of the feature type - for example, AppFeatureBoardView	Yes
`name`	A string of the feature name	No
`build`	An object of the config of the feature's deployment	Yes
`build.kind`	A string of the type of deployment - eg `monday-code` or `url`	Yes
`build.url`	A string representing the URL the app is served from. If the app is served from a custom URL, it should be the full URL. If the app is served from monday code, it should be the path of the URL only.	No
`data`	An object of the configuration of the app feature; the object's attributes are different per app feature	Yes