Building Miro Apps at ServiceRocket

Beginning our journey into the world of apps in Miro, the visual workspace for innovation

Recently at ServiceRocket, many squads have started delving into new app development on the Miro platform. At a high level, Miro provides a Web SDK for simple apps that run while a user is present and a REST API for offline interactions.

Our quarterly engineering hack weeks have also seen many ideas built on the Miro platform. If you’re curious about how we run remote hack weeks at ServiceRocket, check out this article here.

Additionally, we have also kick-started a new Co-Innovator Program which aims to help us gather feedback from potential users and customers about new apps we have in the pipeline. Miro apps are also part of this journey, so feel free to join us if you’re interested!

Getting started

So how does one start building on Miro?

Firstly, I’d recommend visiting Miro’s developer portal. Once you’ve signed in to your account, you should see this:

This landing page is a great place to get started and should be quite intuitive to follow with various guides and documentation created by Miro.

For those of you who prefer to get your hands dirty or “just show me the code” you can check out the app examples repository on GitHub: https://github.com/miroapp/app-examples

After getting acquainted with the basics of the platform, you can follow along with this step-by-step guide here: https://developers.miro.com/docs/build-your-first-hello-world-app

Tech stack

Here at ServiceRocket, we’re passionate about our tech stack. So much that we actually track it! Check out https://servicerocket.github.io/tech-radar/ to see what we use.

That said, we didn’t stray too far from what most developers are familiar with, so we decided to stick with TypeScript as the main language to develop the app. It’s hard to beat TypeScript since you can develop the full stack in a single language (sorry, Java and Scala lovers).

We also wanted an opinionated web framework and decided to build it with Next.js. Why Next.js? Well, it has a well-defined structure in place, so you don’t need to reinvent the wheel for many trivial things, e.g, routing. An added benefit of adopting Next.js is that we can choose to make use of SSR (server-side rendering) to boost performance when needed.

Another important aspect of our stack is CSS for styling. We went through many iterations with various things, like Tailwind and Chakra UI. However, we ended up scrapping most of it and settled on plain CSS modules and Mirotone. Mirotone is a key component in building Miro apps to ensure that your app fits into the general look and feel of Miro.

An example on how to apply Mirotone styles @ https://www.mirotone.xyz/css

Hosting the app

Shortly after building out an early prototype, we soon realised that we hadn’t figured out how to host the app!

Since we adopted Next.js, the primary option is to host on Vercel. However, this wasn’t possible, as we don’t really use Vercel to host stuff at ServiceRocket. So we had to figure out how to host the app with AWS instead.

After many discussions, we came up with an internal RFC that listed 3 options (the main criteria being that it supports AWS):

• AWS Amplify — https://aws.amazon.com/amplify/
• Serverless Framework — https://www.serverless.com/
• SST — https://sst.dev/

AWS Amplify didn’t make the cut. Although it has an out-of-the-box setup with Next.js, most of the stacks it creates can’t be customized. In addition, you have to connect your GitHub repository to AWS Amplify to get the CI/CD integration working.

Serverless Framework was a close win, as we have shipped many of our apps with this framework. However, it only takes care of the backend stack by default. Although the frontend stack can be supported via AWS CloudFormation templates, we wanted a framework that could cover the full stack of the application without much configuration.

Finally, we have SST. We were quite new to this framework, but after using it for a few days, we were satisfied with how easy it is to deploy full-stack apps. Once an app is set up, it is just one command away from a full deployment in AWS with sst deploy.

Another powerful feature of SST is that it is built on top of AWS Cloud Development Framework (CDK). AWS CDK lets us write our infrastructure stack configurations in pure TypeScript or JavaScript, further reducing the cognitive load on engineers by avoiding switching to different languages within a project. SST also leverages the CDK by introducing its own constructs, like NextJsSite that packages an out-of-the-box stack ready for deploying Next.js apps.

const site = new NextjsSite(stack, "site", {
  path: "packages/web",
  warm: getWarmingConfig(stack.stage),
  environment: {
    APP_BASE_URL: APP_BASE_URL as string,
    APP_ENV: APP_ENV as string,
    MIRO_CLIENT_ID: MIRO_CLIENT_ID as string,
    MIRO_CLIENT_SECRET: MIRO_CLIENT_SECRET as string,
    MIRO_REDIRECT_URL: MIRO_REDIRECT_URL as string
  },
  customDomain: getCustomDomain(stack),
  cdk: {
    distribution: {
      priceClass: getCfPriceClass(stack.stage)
    }
  }
});

Above is a snippet of an Next.js site stack configuration in SST. With a few lines, we can spin up a full-stack Next.js site with CloudFront CDN, custom domains, and various other customisations.

Challenges

We consider ourselves quite new to Miro app development, and therefore had a few challenges while building out new apps:

• Miro apps are self-hosted
  — Coming from something like Atlassian Forge which doesn’t require self-hosting, we needed to find ways to host a new infrastructure stack for Miro apps
• Extension points and APIs are limited
  — We felt the extension points provided e.g. Web SDK and REST API are still quite limited compared to other platforms
  — Regardless, the Miro team iterates very quickly so new APIs and extension points are progressively being added as experimental features so that developers can try them out and provide feedback
• Monetization not built in yet
  — The Miro app ecosystem has a marketplace where customers can find apps and install them
  — However it is up to app vendors to integrate into their own payment and pricing systems
• Automated end-to-end (e2e) app testing
  — Our squad has attempted to spike into building out e2e tests on Miro, however faced a few issues
  — Canvas elements are hard to test
  — Lacking a proper testing framework

Pros

Despite having some challenges while starting out in the Miro ecosystem, there are a few things that make Miro app development great:

• Great documentation
  — The documentation site has many code snippets, and even allows you to test API requests
  — App examples repository
• Easy developer on-boarding process
  — Spin up a new Miro app in 5 minutes with https://www.npmjs.com/package/create-miro-app
• Local app runs on localhost without need to deal with CORS!
• Discord! Many Mironeers are happy to answer questions and queries in the various channels on the Discord server
• Developer Community Forum
  — The forum is a great place to ask questions and find answers to common issues: https://community.miro.com/developer-platform-and-apis-57

Wrapping up

This is just the beginning of our journey into the world of Miro apps. We’re committed to building great experiences for customers will continue to work with Miro to enrich their platform and ecosystem.