The app manifest is a manifest.json file that declaratively defines your application. It includes your app's complete configuration, from the basic information to OAuth settings, feature definitions, and endpoints.

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

Use cases

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

Maintain consistent app setup across accounts or environments
Compare the configuration between versions, and rollback to the 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

Concepts

Manifest Schema

The manifest schema defines the required data fields 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}}"
  } 
}

Limitations

Please take into account 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.

Implementation

Prerequisites

Access to the monday apps CLI

Export a manifest

This command exports the manifest of a specific app. 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>

Build types and their deployments

Each app feature uses a build.kind value that determines how the feature is implemented and deployed. The manifest itself doesn't create deployments; it only references code that already exists.

There are three supported build types:

`build.kind: "monday-code"`

This build type is used for monday code deployments. It loads the feature from a monday code bundle deployed in the Developer Center.

Deploy using the CLI.
After deployment finishes, configure the feature:

"build": {
  "kind": "monday-code",
  "url": "/path/to/app"
}

No mapping is required since the manifest directly references the deployed monday code path.

`build.kind: "url"`

This build type is used for externally hosted applications. It loads a feature from a public HTTPS URL.

Deployment happens outside monday.com. Once the app is hosted, specify:

"build": {
  "kind": "url",
  "url": "https://yourapp.com/"
}

No mapping is required since the feature directly loads from the specified URL.

`build.kind: "view"`

This build type is used for client-side deployments. It loads a feature from one of your app’s client-side deployments created in the Developer Center. The manifest does not specify a URL or deployment ID. It only declares that the feature uses a view.

Deploy your client-side code via the CLI or in the Developer Center.
Ensure the deployment appears under the app’s client-side deployments list.
During manifest import, you will be asked to map each build.kind: "view" feature to one of the app’s existing client-side deployments in the Developer Center. This mapping is stored in the app configuration, not the manifest.

Example

You can define a subroute in your manifest file so the feature loads from a specific path within your deployment.

"build": {
  "url": "/login",
  "kind": "view"
}

If your client-side deployment’s base URL is https://example-view-deployment.example.com the full feature URL becomes https://example-view-deployment.example.com/login.

This allows you to route multiple features within the same view deployment and update those routes directly in the manifest file, as long as the deployed bundle supports the corresponding client-side path.

Reference

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": "admin-view",
        "type": "AppFeatureAccountSettingsView",
        "name": "Administration view",
        "build": {
          "kind": "view" // Uses an existing client-side deployment selected during import
        },
        "data": {
          "name": "Administration view",
          "mode": "iframe",
          "description": "Admin configuration that uses the Audit Log API to display recent security or activity events, helping admins track changes and investigate issues"
        }
      },
      {
        "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_params": 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_params": 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_params": 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_params": true,
          "name": "Board View feature",
          "uploading": false,
          "feedbackLink": "",
          "description": " "
        }
      }
    ]
  }
}

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 describing how this feature is deployed. Supported values: `monday-code`: Deployed using monday code `url`: Loaded from an external URL `view`: Uses a client-side deployment that already exists for this app. The manifest does not include a URL or deployment reference; instead, you select the deployment in the Developer Center during the import flow. Note: You must first deploy your code before mapping the feature to the deployment using `build.kind: view`.	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