Quick start

Canva's app development platform lets anyone create apps that add features to Canva. This quick start guide explains how to get your first app up and running in a matter of minutes.

Prerequisites

• You have a Canva.com account.
• You have access to the Canva API beta. (If not, join the waitlist.)
• You're familiar with TypeScript, React, and webpack.

Step 1: Create an app via the Developer Portal

The Developer Portal is the section of Canva's website where developers can create, configure, preview, and manage their apps.

To create an app via the Developer Portal:

1. Log in to the Developer Portal.
2. Navigate to Your apps.
3. Click Create app.

By default, apps are called Untitled app. You can customize this name via the Add details page.

Step 2: Set up the starter kit

The easiest way to get up and running is with our starter kit. This is a GitHub repo that contains the dependencies and build tooling we recommend, including:

• TypeScript
• React
• webpack

This guide assumes you're using the starter kit, but you could use almost any programming language, framework, or build tool. The only strict requirement is that the final output is a JavaScript bundle.

To use the starter kit:

1. Clone the repo:

   git clone [email protected]:canva-sdks/canva-api-starter-kit-beta.git

2. Navigate into repo's directory:

   cd canva-api-starter-kit-beta

3. Install the dependencies:

   npm install

4. Start the local development server:

   npm start

The local development server becomes available at http://localhost:8080.

Step 3: Preview the app

The local development server only exposes a JavaScript bundle, so you can't preview an app by visiting http://localhost:8080. You can only preview an app via the Canva editor.

To preview an app:

1. Navigate to the app’s Configure your app page.
2. Select Extension source > Development URL.
3. In the Development URL field, enter the URL of the development server.
4. Click Preview. This opens the Canva editor (and the app) in a new tab.
5. Click Use. (This screen only appears when using an app for the first time.)

A "Hello world" example appears in the side panel.

Step 4: Make a change to the app

The "Hello world" example is defined in the src/app.tsx file.

This file exports an App component, which define's the app's UI and implements its behavior.

If you update the code while the development server is running, the app's JavaScript bundle is automatically rebuilt. To preview these changes, close and re-open the app in the Canva editor.

Step 5: Use Canva's APIs

In the Canva editor, apps run inside an iframe.

Canva injects a number of APIs into this iframe and attaches them to the window object. Apps can access these APIs at runtime and call the methods they expose. It's these APIs that let an app interact with the Canva editor.

The APIs are organized into distinct capabilities, including:

• Authentication
• Content
• Data Provider
• Design Interaction
• Drag and Drop

By composing these capabilities into unique combinations, apps can implement entirely new behaviors.

Initializing capabilities

When capabilities are injected into the iframe, they're attached to the window object:

console.log(window.canva.designInteraction);

The starter kit contains helper functions for accessing the capabilities:

import { getDesignInteraction } from "@canva/design-interaction";
const designInteraction = getDesignInteraction();
console.log(designInteraction); // => DesignInteraction

These functions:

• Throw an error if the capability is unavailable
• Provide type-safety when using TypeScript

Using capabilities

Each capability returns an object that contains the methods an app can call throughout its lifecycle. For example, the following snippet demonstrates the addNativeElement method of the Design Interaction capability:

const designInteraction = getDesignInteraction();

designInteraction.addNativeElement({
  type: "TEXT",
  children: ["Hello world"],
});

The available methods are detailed in the documentation of each capability.

Step 6: Explore the example apps

The starter kit contains a number of example apps. These apps demonstrate all of the available APIs, which make them a useful companion to the written documentation.

You can find these apps in the examples directory and preview them with the npm start command:

To preview an example, run the following command:

npm start <example_name>

For example, the following command runs the native_text_elements example:

npm start native_text_elements

To learn more, see the README.md file in the starter kit.