Build a full-stack (Next.js) app

This tutorial shows you how to get a simple app running in Miro using the Miro Web SDK. By the end of this guide, you'll have built an app that displays a sticky note on the board with the text Hello, World!.

If you've never built a Miro app before, you're in the right place. Let's get started!

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 app

1. Open the terminal and run:

   npx create-miro-app@latest
   

2. Give your app a name, or press ↵ Enter to use the default app name: my-miro-app.

3. Select your framework: Next.js framework with Web SDK and API client installed

   This framework includes the Miro Node.js client library optimized for the Next.js framework.

   Note: You will need to set the callback URL to use the REST API portion of the app but you should be able to use http://localhost:3000/api/redirect as the redirect URL. Make sure to add it in the app settings page on developers.miro.com for the relevant app.

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

   • JavaScript
   • TypeScript

The CLI will create a new app in the current directory.

Step 2: Set up the app

After the app has been created:

1. Copy the link displayed in the terminal and paste it into your browser. This link will take you to the Miro Developer Dashboard, where you can create a new app.
2. In the Create new app form:
   1. Type the App name.
   2. Select your Developer team.
   3. Select the Expire user authorization token option.
   4. Select Create app.
3. In the App Credentials section, copy the Client ID and Client Secret values.
4. In your app folder, update the .env file with your app credentials.
5. For MIRO_REDIRECT_URL, use http://localhost:3000/api/redirect.

Step 3: Install the app

To install the app for your Developer team:

1. In the Miro Developer Dashboard, select Install app and get OAuth token.
2. Select your Developer team.
3. Select Add.

Step 4: Run the app

To run and test your app:

1. In the terminal, navigate to the app folder:

   cd my-miro-app
   

2. From the app folder, start the app by running:

   npm run start
   

3. In Miro, go to the board where you want to install the app.

4. Select the Plus icon in the bottom-left corner, then find and select your app in the list.

Your Miro app should now display two buttons: Add a sticky and Login. Selecting Add a sticky will place a "Hello, World!" sticky note onto the board. Clicking Login will initiate the OAuth flow, allowing you to select a team to integrate the app with. After completing the process, you'll see a list of your available boards in Miro.

Congratulations on building your first full-stack Miro app!

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

• Get acquainted with fundamental concepts about Miro platform development.
• Learn how to create and interact with items on the board.
• Look through our Web SDK reference to get ideas about what to build next.
• Explore our design guidelines and best practices that dive into the details of building good Miro apps that help you provide a great user experience.
• When you're ready to take your app from development to deployed, you'll want to know more about how to submit your app.