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:
- Log in to the Developer Portal.
- Navigate to Your apps.
- 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:
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:
-
Clone the repo:
git clone [email protected]:canva-sdks/canva-api-starter-kit-beta.git -
Navigate into repo's directory:
cd canva-api-starter-kit-beta -
Install the dependencies:
npm install -
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:
- Navigate to the app’s Configure your app page.
- Select Extension source > Development URL.
- In the Development URL field, enter the URL of the development server.
- Click Preview. This opens the Canva editor (and the app) in a new tab.
- 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:
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.