Build your first Hello, World app

The Miro Web SDK sample app includes boilerplate and scaffolding to make it fast and easy to run a Miro app on a board.

This tutorial shows you how to get a simple app running in Miro using the Miro Web SDK.
If you've never built a Miro app before, you're in the right place. Welcome, and let's get started!
By the end of this guide, you'll have an app that displays a sticky note, with the text Hello, World!, on the board.

Prerequisites

Before you begin, ensure that you have the following prerequisites:

  • You have a Developer team.
  • Your development environment includes Node.js 14.15 or a later version.
  • To run your app locally, your web browser must allow the HTTP transport protocol.
    Recommended web browser: Google Chrome
    Apple Safari doesn't allow HTTP; therefore, it doesn't allow the sample app to run locally.

Step 1: bootstrap the hello world app

  1. Open the terminal and run:
    npx [email protected]
    

  1. Provide a name for your application or press Enter ↩ to use the default application name, my-miro-app.

  2. Select your framework.
    If you're creating an app that uses only the Web SDK, select one of these options:

    • React
    • Vanilla
    • Vue

    If you're creating an app that features also a backend, select one of these options:

  3. Select your flavor.
    Choose one of the following options:

    • JavaScript
    • TypeScript
  4. Change the directory to the my-miro-app folder, where my-miro-app is the application name that you provided in step 2.

    cd my-miro-app
    
  5. To install dependencies, run:

    npm install
    
  6. To start the app and begin developing, run:

    npm start
    
  7. Copy the app URL from the console output.
    Keep your app URL handy: you'll need this URL when you configure and install your app in Miro.
    The URL should look like this:

    http://localhost:3000/
    
  8. Open your browser, paste the URL you just copied in step 7, and press Enter ↩.
    A message indicating that your app is now running locally appears.


    Figure 1. Your app is running locally.

Step 2: create your app in Miro

  1. Click your user account avatar, and then select Settings.

  2. In your Profile settings, select the Your apps tab.

  3. On the Your apps page, review the Terms and Conditions, and then select the I agree to the Terms and Conditions checkbox.

  4. The Create new app button becomes available: click it to get started.



    Figure 3. Select the checkbox to accept the terms and conditions before proceeding to creating a new app.

  5. On the Create new app window:
    a. In the App name box, enter Hello world.
    b. Click Create app.



    Figure 2. On the Create new app modal, give the app a name and make it available for a team.

Step 3: configure your app in Miro

  1. On the app settings page, scroll down to the App URL section.
  2. In the App URL field (Figure 5), enter the URL you obtained in the Bootstrap the Hello, World app step, and then click Save.
    ℹ️ The URL should look like this: htp://localhost:3000/

    Figure 5. App URL.
  3. Under Permissions, select the boards:read and the boards:write checkbox (Figure 6).

    Figure 6. Web SDK version and permissions.

Step 4: install your app

  1. Under the Permissions section, click Install app and get OAuth token.

  2. On the Install app to get OAuth token dialog:

    • In the Select a team list, select Dev team.

      Figure 7. Install app to get OAuth token dialog.

    • Click Install & authorize. A message notifies you that the app is installed.
      For now, ignore the access token information as the Hello world sample app uses only the Miro Web SDK, which doesn't require an access token.

      Figure 8. Installation confirmation and tokens.

    • Click Close.

Step 5: try out your app in Miro

  1. Open your Miro dashboard. Click the Dev team (DT icon on the left pane), and then click New board.

  2. If the Template Picker appears, close the window.

  3. Click >> or ... on the toolbar on the left side of the board, and then click Hello World.

    You should see a sticky note, with the text Hello, World, on the board.

You did it!

Congratulations on building your first Miro app. The Miro Developer Platform allows you to create all kinds of fun, useful apps and integrations. It’s flexible enough to let you build what you want while being powerful enough to support essential workflows for you and your team.

We have many more examples of other apps and ideas you can build check Miro App Examples to find more.

Here's a list of topics you may want to check out:


What’s Next

Learn how to reflect on the board updates to board item properties by syncing the changed board items.