Quickstart guide
Step-by-step instructions to build a simple client-side monday app with React!
This tutorial walks you through each step to building a simple Hello World app with React. We will start simple and create a more complex app as we go. You can use the same code as a board view, item view, or dashboard widget.
The monday apps framework serves as a set of tools to build on top of monday.com. One 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 may contain just a single board view or use multiple views, widgets, and integrations to create a set of functionality that extends across contexts.
Supported frameworks
This tutorial functions solely as an example, but we wrote it with React. You can use any JS framework you want, or you can use none when building your monday apps.
You can also build your server with any language (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
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.
Configure your monday app
Create your monday app
- Navigate to the Developers section and click Create App.
- Open the Features tab.
-
Select the feature you would like to add from Board View, Account Settings View, or Dashboard Widget.
-
Choose a template or build your own from scratch. For this tutorial, we will select Quickstart - ReactJS
Set up your development environment
After selecting Quickstart - ReactJS, you will need to set up your development environment. We will use the monday-cli
package to download the example code and run it locally.
-
Run the following command.
Note: 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
- Wait for the installation process to finish. Keep in mind that it may take a few minutes.
- After the app is installed and running, you will see a message that says Your app is served from this URL with a link to your app (e.g.
https://abc1234asdlqwe.loca.lit
). - Paste this URL in the Custom URL field in the View Setup pane.
- If you want to run your application manually in the future, navigate to the folder with the project (quickstart-react) and run "npm run start" command.
Update your view's basic information
After setting up your development environment, the system automatically redirects you to the Feature Editor.
-
Open the Feature Details tab.
Note: This is where you can add a title and description to your board view or widget. Users will see the title and description when they see your view or widget on the view or dashboards center.
-
You can update the feature's name, description, learn more from link, or feedback link. You can also choose whether or not you want to hide the board controls.
-
Save your changes and navigate to the View Setup tab.
-
The tab will show you the initial example app and display Hello monday apps.
-
You should now be able to load up the app for the first time using your tunnel URL. Pretty exciting!
We've recently added an Attention Box element from our design elements to the app's initial load. It looks like this when you first open the app:
You can find more info on our design system here. You can also reference the Attention Box element.
Build your monday app
In this section, we will write code to display "Hello monday Apps" in a board view or widget.
Edit src/App.js
to include a simple UI
src/App.js
to include a simple UI-
Navigate to the quickstart-react folder.
-
Open the
App.js
file downloaded in the starter code package. -
In the function
App
, you will see areturn()
function. -
If you want to replace the text displayed in the Attention Box, you can use the
text
property within the Attention Box element. This is assigned to theattentionBoxText
variable. Replace the text with whatever content you want, and it will display in the attention box.Note: Your
return()
method should look something like this after these steps:
const attentionBoxText = `Ready to start my app journey by building a view!`
return (
<div className="App">
<AttentionBox
title="Hello Monday Apps!"
text={attentionBoxText}
type="success"
/>
</div>
);
Navigate to Preview after opening the View Setup section. You will see this:
Now we're able to edit a style element from our Design System!
Upload your monday app build
To build our simple application, we will bundle it in a ZIP file and upload it to the monday.com server.
- Compile your React code into a production build by running
npm run-script build
. This command will create a new Build folder in your directory. - Create an archive of the contents of your Build folder (ZIP file).
- Open your feature and select the Builds tab. Click New Build to upload your production code.
- Upload the ZIP you just created.
- Open a board and add your view to it. Your app should display data for the first item on the board.
Security in our CDN
When you upload a client-side app to our platform, it is hosted on the monday.com apps CDN. Note that this CDN does not have authentication on it. 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 and allows anyone in your account to use it. You and your collaborators will now see your app on your boards!
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎
Updated 9 months ago