/widget-sdk-docs

A repo for drafting docs for the Widget SDK project.

What's Canvas SDK

Canvas SDK is a JavaScript library that contains everything developers need to create new widgets.

Widgets are Miro entities, similar to stickies and images. They can be interactive, animated, and use high-fidelity graphics.

New widgets can be developed without modifying the Miro codebase. This allows to rapidly expand Miro capabilities and eventually, also open up Widget development to third parties.

Before you begin

  1. Make sure you've set up VPN.

  2. Clone the Canvas SDK repository to your machine. This monorepo contains various project published as NPM packages.

    git clone git@github.com:miroapp-dev/surface.git

Setting up the environment

Make sure you have installed:

  1. Brew
  2. Xcode
  3. Python 3
  4. NPM
  5. Bazel

Brew

Install Brew.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Xcode

Install Xcode version 12 or higher.

To check the version of Xcode, run:

/usr/bin/xcodebuild -version`

The result should look similar to this:

Xcode 15.0.1
Build version 15A507

Check that xcode-select is configured to use xcodebuild, not command line tools:

xcode-select -p
/Applications/Xcode.app/Contents/Developer

If you get some other response, run:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`

Additionally, make sure to clean Bazel cache by running bazel clean --expunge.

NPM

Your NPM credentials must be set up correctly. Run the following command to check your credentials:

npm whoami

The result should print you username.

⚠️ Important: If you get a different response or an error, follow these steps to configure private registry credentials.

Python

You should have Python 3 installed and python3 command should work:

python3 --version
Python3 3.11.5

If you get a different response, you may need to symlink python to python3, or run brew install python3 to install Python 3.

Bazel

Everything is built using Bazel. We use Bazelisk — a wrapper for Bazel, which automatically picks the right version of Bazel with respect to your current working directory and downloads it from the official server.

To install Bazelisk, use one of the following methods:

  1. With brew: brew install bazelisk
  2. With npm: npm install -g @bazel/bazelisk

Explore Canvas SDK

The Canvas SDK contains the following projects:

  1. WidgetClient
  2. CanvasAPI
  3. SurfaceWidgetSDK
  4. New Engine
  5. WidgetEditor

WidgetClient playground

A standalone playground to explore the rendering engine and SurfaceWidgetSDK.

Run the following command to start the playground:

bazel run //:WidgetClient

Open the browser and navigate to http://localhost:8080/.

  • Language: TypeScript
  • Location: src/Frontend/WidgetClient/
  • README

CanvasAPI

TBD: A declarative, stateless, and retained mode graphics API.

  • Language: TypeScript
  • Location: src/CanvasAPI/
  • API documentation: TBA
  • README

SurfaceWidgetSDK

TBD: An SDK for developing widgets using a React-like API.

New Engine

2D-vector rendering engine for SurfaceWidgetSDK.

WidgetEditor

A React component that wraps the Monaco Code Editor fully configured for developing widgets.

  • Language: TypeScript
  • Location: src/WidgetEditor/
  • README

Read more

  1. Confluence: Canvas SDK overview
  2. Confluence: Synced state
  3. Miro: Technical overview