monday Apps Platform

monday Software Development Kit

monday.com Apps framework SDK for JavaScript

GitHub license   npm version   npm   jsDelivr hits (npm)

The monday.com SDK provides a toolset for application developers to build features and solutions on top of the monday.com Work OS platform. You'll find this SDK useful if you want to:

  • Access monday.com account data from your application, by utilizing the GraphQL client
  • Build Board Views & Dashboard Widgets that extend the monday.com UI
  • Build Integrations & Automations using your own external services and business logic

The SDK contains methods for server-side and client-side application development. Client-side capabilities assume a valid user session is present (and can seamlessly act on behalf of that user), while server-side methods can be used to access monday.com features using explicit credentials but without any client-side code.

Table of contents

Usage

Using as an npm module

Install the SDK as a module:

npm install monday-sdk-js --save

Then import into your project:

import mondaySdk from "monday-sdk-js";
const monday = mondaySdk();

As a <script> tag directly in your HTML code

You can also load the SDK directly into your HTML code by adding:

<head>
  <script src="https://cdn.jsdelivr.net/npm/monday-sdk-js/dist/main.js"></script>
</head>

and then initialize the SDK anywhere in the page by declaring:

const monday = window.mondaySdk()

Seamless authentication

When used for client-side development, SDK methods that require to act on behalf of the connected user will work out-of-the-box by communicating with the parent monday.com running application. You're not required to initialize the SDK client with any explicit credentials.

Methods that use seamless authentication (including monday.api and monday.storage) offer capabilities that are scoped based on the permissions of the logged in user and the scopes you have configured in your app.

SDK capabilities

The SDK exposes the following capabilities:

SDK ObjectCapability
monday.apiPerforming queries against the monday.com API on behalf of the connected user
monday.listenListen to client-side events on the monday.com client running this app
monday.getRetrieve information from the monday.com client running this app
monday.executeCall an action on the monday.com client running this app
monday.storageRead/write to the Storage API, a key-value storage service for apps
monday.oauthRedirecting the client to the OAuth authorization server, with your client ID included

monday.api(query, options = {})

Used for querying the monday.com GraphQL API seamlessly on behalf of the connected user, or using a provided API token.

Parameters:

  • query: A GraphQL query, can be either a query (retrieval operation) or a mutation (creation/update/deletion operation). Placeholders may be used, which will be substituted by the variables object passed within the options.
  • options:
OptionDescriptionRequiredDefault
tokenAccess token for the APIOnly on serverIf not set, will use the credentials of the current user (client only)
variablesAn object containing GraphQL query variablesNo

Instead of passing the API token to the api() method on each request, you can set the API token once using:

monday.setToken('mytoken')

Returns:

A Promise that will be resolved to the API response.

Examples:

A client-side query that fetch the ID and name of all the users within the account that the connected user is allowed to view:

monday.api(`query { users { id, name } }`).then(res => {
  console.log(res);
  /* { data: { users: [{id: 12312, name: "Bart Simpson"}, {id: 423423, name: "Homer Simpson"}] } } */
});

A server-side query that fetches all the names of users in the account:

monday.setToken('ac5eb492f8c...');
monday.api('query { users { name } }').then(res => {...})

A mutation that sends an in-app notification to user user_id, which upon clicking will take the user to item item_id:

monday.api(`
  mutation {
    create_notification(
      text: "I've got a notification for you!",
      user_id: ${user_id},
      target_id: ${item_id},
      target_type: Project,
      internal: true
    ) { 
      id 
    }
  }
`);

For more information about the GraphQL API and all queries and mutations possible, read the API Documentation


monday.get(type, params = {})

Used for retrieving data from the parent monday.com application where your app is currently running. This object can only be used when your app is running inside an iframe. This can only be used in client-side apps.

Parameters:

  • type: The type of requested information (available values below)
  • params: Reserved for future use

The available types that can be requested are: | Type | Description | |--|--| | 'context' | Information about where this app is currently displayed, depending on the type of feature | | 'settings' | The application settings as configured by the user that installed the app | | 'itemIds' | The list of item IDs that are filtered in the current board (or all items if no filters are applied) | | 'sessionToken' | A JWT token which is decoded with your app's secret and can be used as a session token between your app's frontend & backend |

Returns:

A Promise that will be resolved with the requested data.

Examples:

Requesting context and settings data:

monday.get("settings").then(res => ...);
monday.get("context").then(res => ...);

Example context objects that return for a board view and a dashboard widget:

// Board view context
{
  "boardViewId": 19324,
  "boardId": 3423243,
  "mode": "fullScreen", // or "split"
  "theme": "light"  // or "dark"
}

// Dashboard widget context
{
  "widgetId": 54236,
  "boardIds": [3423243, 943728],
  "theme": "light"  // or "dark"
}

Requesting the list of items currently in view in the board:

monday.get("itemIds").then(res => console.log(res));
// => [234234, 4564, 234234, 67675, 576567]

monday.listen(typeOrTypes, callback, params = {})

Creates a listener which allows subscribing to certain types of client-side events.

Parameters:

  • typeOrTypes: The type, or array of types, of events to subscribe to
  • callback: A callback function that is fired when the listener is triggered by a client-side event
  • params: Reserved for future use

You can subscribe to the following types of events: | Type | Description | |--|--| | 'context' | Fired when one of the parameters in the context changes | | 'settings' | Fired when a setting value is changed by the user | | 'itemIds' | Fired when the board filter changes, which impacts the list of items currently in view | | 'events' | Fired when an interaction takes place with the board/dashboard |

Returns:

This method does not have a return value.

Examples:

Subscribe to changes in settings and context:

const callback = res => console.log(res);
monday.listen(['settings', 'context'], callback);

Subscribe to interaction-based events on the board:

const callback = res => console.log(res);
const unsubscribe = monday.listen("events", callback);

// When an item/s are created on the board:
// => { type: "new_items", itemIds: [5543, 5544, 5545], boardId: 3425 }

// When a column value changes for one of the items:
// => { type: "change_column_value", itemId: 12342, value: {...} }

monday.execute(type, params)

Invokes an action on the parent monday client.

Parameters:

  • type: Which action to perform
  • params: Optional parameters for the action

Returns:

A Promise that will optionally be resolved to the return value from the action executed

Action types:

Open item card

Opens a popup card with information from the selected item

type 'openItemCard'

params

ParameterTypeDescriptionRequiredDefault Value
itemIdIntegerThe ID of the item to openYes
kindStringOn which view to open the item card.
Can be "updates" / "columns"
No"columns"

Example

monday.execute('openItemCard', { itemId: item.id });

Confirmation dialog

Opens a confirmation dialog to the user type 'confirm'

params

ParameterTypeDescriptionRequiredDefault Value
messageStringThe message to display in the dialogYes
confirmButtonStringThe text for the confirmation buttonNo"OK"
cancelButtonStringThe text for the cancel buttonNo"Cancel"
excludeCancelButtonBooleanEither to axclude the cancel buttonNofalse

Example

monday.execute("confirm", {
   message: "Are you sure?", 
   confirmButton: "Let's go!", 
   cancelButton: "No way", 
   excludeCancelButton: false
}).then((res) => {
    console.log(res.data);
    // {"confirm": true}
});

Notice message

Display a message at the top of the user's page. Usefull for success, error & general messages.

type 'notice'

params

ParameterTypeDescriptionRequiredDefault Value
messageStringThe message to displayYes
typeStringThe type of message to display . Can be "success" (green), "error" (red) or "info" (blue)No"info"
timeoutIntegerThe number of milliseconds to show the message until it closesNo5000

Example

monday.execute("notice", { 
   message: "I'm a success message",
   type: "success", // or "error" (red), or "info" (blue)
   timeout: 10000,
});

monday.oauth(options = {})

Performs a client-side redirection of the user to the monday OAuth screen with your client ID embedded in the URL, in order to get their approval to generate a temporary OAuth token based on your requested permission scopes.

Parameters:

  • options: An object with options as specified below
OptionRequiredDescription
clientIdNo, defaults to your client IDThe OAuth client ID of the requesting application
mondayOauthUrlNoThe URL of the monday OAuth endpoint

Returns:

This method does not have a return value.


monday.storage

Provides access to the Storage API. See below for methods and explanation.


Storage API (monday.storage)

The Storage API is in early beta stages, its API is likely to change

The monday apps infrastructure includes a persistent, key-value database storage that developers can leverage to store data without having to create their own backend and maintain their own database.

The database currently offers instance-level storage only, meaning that each application instance (i.e. a single board view or a dashboard widget) maintains its own storage. Apps cannot share storage across accounts or even across apps installed in the same location.

Available methods:

  • monday.storage.instance.getItem(key) - Returns a stored value from the database under key
  • monday.storage.instance.setItem(key, value) - Stores value under key in the database

Returns:

All methods return a Promise which will be resolved to the Storage API's response

Versioning:

You may face cases where multiple monday.com users will be working on the same app instance and writing to the same key in an unsynchronized fashion. If you're storing a compound data structure (like JSON) in that key, such operations may overwrite each other.

The getItem() and setItem() each return a version identifier which can be used to identify which value is currently stored in a key. Whenever a write that changes the value occurs, the version identifier in the database changes. This allows you to identify whether a value was already changed from another location and prevent that from being overwritten.

Example of using versioning:

monday.storage.instance.getItem('serialKey').then(res => {
  const { value, version } = res.data;
  sleep(10000); // someone may overwrite serialKey during this time

  monday.storage.instance.setItem('serialKey', { previous_version: version }).then(res => {
    console.log(res);
  }
});
// => '{ "success": false, "reason": "version_conflict" }'

Examples:

Store a value in the database:

monday.storage.instance.setItem('mykey', 'Lorem Ipsum').then(res => {
  console.log(res);
}
// => { "success": true }

Retrieve a previously stored value in the database:

monday.storage.instance.getItem('mykey').then(res => {
   console.log(res.data.value);
}
// => 'Lorem Ipsum'