monday apps framework

The monday apps framework Developer Hub

Welcome to the monday apps framework developer hub. You'll find comprehensive guides and documentation to help you start working with monday apps framework as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Quickstart Guide: Views & Widgets

Build a simple client-side monday app with React, step by step!

In this tutorial, we will build a simple Hello World app with React. This tutorial will start simple, and build a more complex app as it goes along. The same code can be used as a board view, item view or a dashboard widget.

The monday apps framework is a set of tools you can use to build on top of monday.com. A single monday app can contain multiple features, and the platform supports adding board views, item views, dashboard widgets, automations and integrations to your apps. A simple app might contain just a single board view, or use multiple views, widgets and integrations to create a set of functionality that extends across contexts.

πŸ“˜

What frameworks can I use?

This tutorial is written with React, but it's just an example. You can use any JS framework you want (or none at all) when building your monday apps.

You can also build your server with any language you'd like (PHP, Python, etc). Keep in mind that views and widgets run in a client's browser, so they'll need to compile into HTML/CSS/Javascript.

Before we begin

You will learn:

  • How to build a simple "Hello world" app in React
  • How to package and build your app
  • How to allow users to configure settings for your app
  • How to use our SDK to get data from connected boards

Prerequisites

  • Basic understanding of how to create a monday app. To learn more, check out this guide.
  • Basic understanding of web programming (HTML, CSS, JS)
  • Working environment of NodeJS on your computer, as well as a package manager like npm or yarn.
  • A monday.com account. If you don't have one, sign up for a free developer account here.

Part 1: Set up your development environment

Create a monday app

Open the developers section and create a new monday app. Go to the "Features" tab and add a new board view (or widget).

Update your view's basic information

In the feature editor, open the "feature details" tab. This is where you can add a title and description to your board view or widget. The user will see the title and description when they see your view or widget when they explore the view or dashboards center.

Add a new featureAdd a new feature

After this step, you should be able to load up the app for the first time using your tunnel URL. Pretty exciting!

We've just recently added an Attention Box element from our Design Elements to the initial load of the app, and it looks like this when you first open the app:

hello_monday_attention_boxhello_monday_attention_box

You can find more info on our Design System here, and here's a reference to the Attention Box element as well.

Set up your development environment

We will be using the monday-cli package to download the example code and run it locally. To set up your dev environment, follow these steps:

  1. Run the following command. This will download the project quickstart-react to your current folder, install the dependencies (npm install), and run the project locally (npm run start).
npx @mondaydotcomorg/monday-cli scaffold run ./ quickstart-react
  1. Wait for the installation process to finish. It may take a few minutes.
  2. After the app is installed and running, you will get the message "Your app is served from this URL" with a link to your app, e.g. https://abc1234asdlqwe.loca.lit
  3. Paste this URL to the "Custom URL field" in the "View Setup" pane.

To run your application manually in the future: navigate to the folder with the project (quickstart-react), and run "npm run start" command.

Part 2: Build a simple "Hello monday" app

In this section, we will write some code to display "Hello monday Apps" in a board view or widget.

Edit src/App.js to include a simple UI

Navigate to quickstart-react folder.

Open App.js file that you downloaded in the starter code package.

In the class App() you will see a render() function.

If you want to replace the text displayed in the Attention Box, you can use the text property within the Attention Box element. Replace the text with the words Ready to start my app journey by building a view!. This will display the text "Hello monday Apps!" in your Attention Box within the Board VIew or Widget.

After this step, your App() class will look something like this:

class App() extends React.Component {
  render() {
    return (
      <div className="App">
      <AttentionBox
        title="Hello monday Apps!"
        text="Ready to start my app journey by building a view!"
        type="success"
      />
      </div>
    );
  }
}

When you open the "View Setup" section, go to "preview" and you will see this:
hello_monday_first_stephello_monday_first_step

We're already able to edit a style element from our Design System. Off to a great start!

Part 3: Use settings to let the user customize their experience

Now that we have built a simple app, we will extend the functionality of this app to include user configuration.

In this section, we will allow the user to select the color of app's background (the same way we can use any monday field type), and with the newest Attention Box element, we can also add some fields to change what is displayed there as well.

To do this, we will first add a settings field to our feature to get the color value as an input. We can also add additional setting fields to control the title, text and the type of attention box that is displayed, according to the Design system.

Then, we will use the monday SDK to retrieve this settings value and use it in our view or widget.

Adding a color picker settings field to your view or widget

In this step, we will add a color picker setting to our view (or widget). Later, we will update our code to retrieve this setting.

  1. Open your app's feature. Open the "View Setup" (or "Widget Setup") pane.
  2. On the "View Settings" pane on the right, select the blue "Add Field" button. This will let you add a new field to your feature's settings.
  3. In the field selector, choose "Color Picker". This setting field will let the user choose a color.
  4. In the field configuration page, change the title to "Background Color". Change the "name" field to "background" -- this is the key we will use to access the setting's value later.
  5. Click done, and save.

πŸ“˜

NOTE

These are the same settings fields we use in native monday.com views!

Adding extra setting fields to change the Attention Box via view settings

To add extra fields that would allow users to control the Attention Box text and type, we can follow similar steps to the above, except this time, we can add text input fields and a dropdown. Here's how:

  1. Open the "View Setup" on your Board View or Widget once more;
  2. On the "View settings" pane, use the same "Add Field" button as before;
  3. This time, select Text to add a Text input field. This can now be used to edit the Text shown as the Title of the Attention Box, or the message it displays;
  4. You can adjust the title of the field to reflect its purpose. Use something concise and clear to make it count! For example, "Attention Box Message", and "Attention Box Title".
  5. Make sure to change the "name" of the field to the key you will use within your code later on. For example, "attentionBoxMessage" for the text inside the Attention Box, and "attentionBoxTitle" for the header of this element.
  6. Click done, and save!

Ah-mazing! You're already a master of adding text and color input fields for the user to play around with, and we're getting deeper and deeper into setting the app up to be customizable. But wait, there's more.

You can follow a similar process to add a Dropdown to the settings as well!

  1. Now, follow the steps above to Add a New Field, and select the Dropdown option;
  2. Change the Title of this field to Attention Box Type;
  3. Change the "name" value to "attentionBoxType", so that you're able to reference this inside your code later on.
  4. Add the options for the user to select the type. As per our Design System, there are 4 available options:
    • main, which will show a Blue box;
    • success, which displays the Attention Box in Green;
    • danger, which returns a Red;
    • dark, which gives us a Grayscale box;

Here's how the Dropdown field setting should look:

hello-monday-dropdown-field-settingshello-monday-dropdown-field-settings

Accessing the settings from your view or widget

Now that we have configured the setting fields, we need to retrieve this setting and use the value in our app. To do this, we will set up an event listener with the monday.listen() method in the SDK.

In the componentDidMount function, we will add the monday.listen() method. This will create a listener to save the settings data to our app's state every time the settings change.

Add the following lines to your componentDidMount:

componentDidMount() {
    monday.listen("settings", res => {
      this.setState({ settings: res.data });
    });
  }

A note about the settings data: it is a Javascript object, where each key is the "name" of the field as configured in your app feature. Since we set the "name" of our color picker field to "background", we can access this particular value by calling settings.background. Use the name values of the other fields you've added, like attentionBoxTitle, attentionBoxMessage, and attentionBoxType to get the values from those fields upon input.

Incorporating the customizable setting fields in your app

Now that we've added functions to retrieve and store our app settings, we need to use this in our app.

To set the background color of our "hello world" app, we will use the style attribute to add the color to our text:

<div className="App" style={{background: (this.state.settings.background)}}>
<AttentionBox
        title="Hello Monday Apps!"
        text="Ready to start my app journey by building a view!"
        type="success"
      />
</div>

By the end of this step, your render() function should look like this:

render() {
  return (
    <div
      className="App"
      style={{background: (this.state.settings.background)}}
      >
      <AttentionBox
        title="Hello Monday Apps!"
        text="Ready to start my app journey by building a view!"
        type="success"
      />
    </div>
  );
}

Part 4: Customize the Attention Box component

Now, we can also reference the other fields we've created earlier to customize the title, message and type of the Attention Box element. We can add similar lines of code to the Attention Box itself:

render() {
    return (
      <div
        className="App"
        style={{ background: this.state.settings.background }}
      >
      <AttentionBox 
      title = {this.state.settings.attentionBoxTitle}
        text={this.state.settings.attentionBoxMessage}
        type={this.state.settings.attentionBoxType}
      />
      </div>
    );
  }
}

This will allow the user to enter a certain value within the fields, and choose the type of the Attention box in the Dropdown to set up the Attention Box in their own special way.

Here's how that would look:

hello-monday-app-successhello-monday-app-success

However, there is a bit of a catch here, and you'll notice that your app looks a bit empty when you first open it, as the setting field is empty by default:

hello-monday-no-defaultshello-monday-no-defaults

Rest assured, we can take care of this within the code itself! Use the || logical OR operator in JavaScript to set a default value to the field, in case the current state is not defined, like so:

<AttentionBox 
title = {this.state.settings.attentionBoxTitle || "Hello monday.apps"}
  text={this.state.settings.attentionBoxMessage || "You should be able to edit the info that appears here using the fields you've set up previously in the View settings :) "}
  type={this.state.settings.attentionBoxType || "success"}
/>

Now, even with no field input from the user, they'll still see the attention box they deserve:

hello-monday-defaults-addedhello-monday-defaults-added

Well done!

We've now used the monday SDK to let your users configure what your app shows them. More great building achievements await!

Next, we will use the monday SDK to count the number of items that are on the boards connected to the view/widget, and display them.

background-color-changingbackground-color-changing

πŸ“˜

Getting other data using the SDK

In a similar way to settings, you can also use the monday SDK in order to get other useful fields.

The "context" field is an important one, and used to understand where your app is currently rendered. You can get the app context by adding another listener - monday.listen(β€œcontext”, this.getContext);

You can find full details about adding context listeners in our SDK Reference.

Part 5: Use the monday API to get board data

In this section, we will use the monday.com API to get the user's name.

Set up your app's permission scopes

We need to set up your app's permission scopes to access the user's name. To do this:

  1. Open your app's details by going to the Developers section and clicking your app.
  2. Click "OAuth and Permissions" on the left.
  3. Enable the "boards:read" scope.
  4. Hit save.

Set up a context listener that calls the monday API

Every board view/widget runs in a specific context and our SDK exposes methods to retrieve this information. The context data looks like this:

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

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

// Item view context 
{
    "boardId" : 12345,
    "itemId" : 123456
}

We will update our code to get the context of your board view/widget, and then make an API call to get the first item from each connected board.

Add the following context listener to your componentDidMount function:

monday.listen("context", res => {
      this.setState({context: res.data});
      console.log(res.data);
      monday.api(`query ($boardIds: [Int]) { boards (ids:$boardIds) { name items(limit:1) { name column_values { title text } } } }`,
        { variables: {boardIds: this.state.context.boardIds} }
      )
      .then(res => {
        this.setState({boardData: res.data});
      });
    })

πŸ‘

Learn more about our API

Our GraphQL API exposes methods to get board data, create items, notify people, and much more. Check out our API documentation for more information.

Change your render() function to include the boardData field:

render() {
    return (
      <div
        className="App"
        style={{ background: this.state.settings.background }}
      >
     <AttentionBox 
     title = {this.state.settings.attentionBoxTitle || "Hello monday.apps"}
     text={this.state.settings.attentionBoxMessage || "You should be able to edit the info that appears here using the fields you've set up previously in the View settings :) "}
     type={this.state.settings.attentionBoxType || "success"}
/>
{JSON.stringify(this.state.boardData, null, 2)}
      </div>
    );
  }
}

Great job!

Your final app should look like this:

final_productfinal_product

Part 6: Build your app

To build our simple application, we will bundle it in a ZIP file and upload it to the monday.com server.

  1. Compile your React code into a production build by running npm run-script build. This will create a new "build" folder in your directory.
  2. Create an archive of the contents of your "build" folder (ZIP file).
  3. Open your feature, and select the "Builds" tab. Click "New Build" to upload your production code.
  4. Upload the ZIP you just created.
  5. Open a board, and add your view to it. You should see your app display data for the first item on the board.

πŸ“˜

NOTE: Security in our CDN

When you upload a client-side app to our platform, it is hosted on the monday.com apps CDN. Do note that this CDN does not have authentication on it. So, any views or widgets uploaded to our platform will be publicly-accessible via a randomly-generated (and difficult to guess) URL.

If this is not suitable for you, you can serve your app via an iframe URL instead.

Congratulations Builder!

You've now built a simple monday app that displays data, is configurable by the user, and can be used by anyone in your account. You and your collaborators will now see your app on your boards.

As you learn more about the apps framework, check out our SDK Reference and Frequently Asked Questions.

Updated 4 months ago


Quickstart Guide: Views & Widgets


Build a simple client-side monday app with React, step by step!

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.