If you're ready to get started with monday code, this is the guide for you. It provides an overview of infrastructure specifications, walks you through how to set up and deploy an app, and demonstrates how to manage your app after deployment. As an added bonus, it covers key features that can help you optimize your monday code usage.

📘

Prefer to start with a code sample?

Install the monday code quickstart app from Github: @mondaycom/welcome-apps

Infrastructure specifications

Set up and deploy

Enable the feature

To start, you must enable monday code on your account (only admins can do this!):

1. Create a new app or open an existing one.
2. Open the Hosting page.
3. Click Connect monday code and accept the terms & conditions.

You can see these steps in the video below:

Install the CLI and SDK

To use monday code, you'll need to install the monday apps CLI (command line interface) and either the JavaScript or Python SDK.

Command line interface

1. You can install the CLI globally through npm by running npm install -g @mondaycom/apps-cli.
2. Run mapps help to test that it worked. You should receive a list of supported commands.
3. Once installed, run mapps init and add your API token once prompted. Follow these steps if you don't know how to get your API token.

Software development kit

When adding monday code to an existing app, navigate to your app's directory and run npm i @mondaycom/apps-sdk to add the Javascript SDK as a dependency.

🚧

JavaScript and Python SDK

We currently support the Javascript and Python SDKs but hope to support more languages in the future!

Deploy your app for the first time

Once you're ready to deploy your app:

1. Use the mapps code:push command to deploy it to monday servers.
2. If you haven't built an app but want to test the deployment process, use our Github Integration built for monday code to test it.

After deployment

Connect your features from the hosting page

The hosting page gives you quick access to connect your features to monday code. There, you'll see all your app features. When you click New Build, you can select an endpoint to connect the feature to:

Get your deployment URL

Once you deploy your app, you'll see the deployment URL on the hosting page. You can use this URL to point to any external services that need to connect to your app:

Check your deployment's status

Check the status of your app's deployments with the following command:

$ mapps code:status -i <APP_VERSION_ID>

Check logs

All logs using the CLI mapps code:logs command can be found using:

$ mapps code:logs -i <APP_VERSION_ID>

Use monday-code's features

monday-code ships with a number of features to make your development process easy.

Store data

We offer two key-value storage APIs for your app to persist data on behalf of a customer. To use these APIs, you need an access token for a given user (either an OAuth token or an integration shortLivedToken).

Storage API

Here's a typical use of the storage API in your app:

import { Storage } from '@mondaycom/apps-sdk';

const storage = new Storage('<ACCESS_TOKEN>');

// set value
const { version } = await storage.set(key, value, { previousVersion, shared });
// retrieve value
const storedValue = await storage.get(key, { shared });
// delete value
await storage.delete(key, { shared });

Secure storage API

The secure storage API works very similarly but is an encrypted store for sensitive information like API keys and PII. You can use it like this:

import { SecureStorage } from '@mondaycom/apps-sdk';
const secureStorage = new SecureStorage();

// set value
await secureStorage.set(key, value);
// retrieve value
const storedValue = await secureStorage.get(key);
// delete value
await secureStorage.delete(key);

📘

A note on security

The primary benefit of monday code is a secure environment and peace of mind for our users. You must use the storage, logging, and enviornment management included in our SDK to be considered secure by our standards.

For example, if you integrate with an external database to store customer data, your app will not be considered as secure as if you used the bundled storage.

Declare environment variables

You can also declare environment variables in the CLI and then use them in your app. Here's an example:

1. Using the CLI, run the command mapps code:env.
2. Follow the steps to add a new environment variable. You will need to provide your app's version ID, the variable's key (eg SIGNING_SECRET) and the value (eg 12345abcd).
3. Once you've added a variable, your app can access it with the following code:

import { EnvironmentVariablesManager } from '@mondaycom/apps-sdk';

// Initialize the environment variables manager without injecting env into `process.env`
let envManager = new EnvironmentVariablesManager();

// Initialize the environment variables manager and inject env into `process.env`
envManager = new EnvironmentVariablesManager({ updateProcessEnv: true });


// Get cached environment variable
const cachedValue = envManager.get(key, { invalidate: false });

// Get the latest version of environment variable
const latestValue = envManager.get(key);

Use the logger

monday code ships with a logger to store application logs. You can view these logs from the CLI and use them to troubleshoot with customers.

Send logs from your app

You can start logging in your app using these methods:

import { Logger } from '@mondaycom/apps-sdk';

const tag = 'app-2322-user-12344';
// tag will be added to every logged message
const logger = new Logger(tag);

logger.info('POST request at /routes/run');
logger.warn('Complexity limit reached. Retrying...');
logger.debug(`account_info: ${JSON.stringify(account_data)}`);
logger.error('Something went wrong', { error: new Error('error') }); // will include stack trace

Access logs through the CLI

You can access logs through the CLI in several ways. For example, you can filter for a specific date range, search term, or logs of a certain type (e.g., info, debug, error).

mapps code:logs [--verbose] [--print-command] [-i <value>] [-t <value>] [-s <value>] [-f <value>] [-e <value>] [-r <value>]