Previewing apps

How to preview apps via the Developer Portal.

After setting up the starter kit, the next step is to preview your app in the Canva editor — and, ideally, preview it at regular intervals.

There are two ways to do this:

  • Generate a JavaScript bundle and upload it via the Developer Portal.
  • Load the app from a local development server.

It'd be tedious to generate and upload a bundle after every change, so the first option is intended for when you're ready to submit the app for review. To learn more, see Bundling apps.

The second option is ideal during development because it offers the fastest development loop.

The starter kit contains webpack configuration for starting a local development server. This server exposes the app's source code via a URL that can be shared with Canva.

To start the local development server:

  1. Navigate into the starter kit:

    cd canva-apps-sdk-starter-kit
    bash
  2. Run the following command:

    npm run start
    bash

The local server is available at http://localhost:8080 by default. If you navigate to this URL, you should see the app's (minified) source code.

By default, the development server does not use the HTTPS protocol. This is convenient because there's no need for a security certificate, but it prevents you from previewing an app in Safari.

If you're using Safari (or otherwise need to use HTTPS):

  1. Start the development server with the --use-https flag:

    npm run start --use-https
    bash
  2. Navigate to https://localhost:8080.

  3. Bypass the invalid security certificate warning:

    1. Click Show details.
    2. Click Visit website.

You'll need to bypass the invalid security certificate warning every time you start the server.

In the Developer Portal, set the App source > Development URL field to the URL of the local development server. This field tells Canva to load the app's source code from the specified URL.

The development URL for an app

The URL must point directly to a standalone JavaScript file.

In the Developer Portal, click the Preview button.

This will open the app in a new tab.

The first time you open an app, it must be connected (installed). To do this, click the Open button. The app will then load within the iframe.

If you make a change to the app — for example, by editing the src/app.tsx file — that change is not immediately reflected in the app's iframe. You need to reload the app to preview the changes.

You can reload an app manually or automatically as the code changes.

To manually reload the app, do any of the following:

  • Click the Reload button in the app's header.

    The reload button at the top of an app's iframe

  • Return to the Developer Portal and click the Preview button.

  • Right-click in the app's iframe and select Reload frame.

  • Close and re-open the app in the Canva editor.

The most efficient way to preview changes is with Hot Module Replacement (HMR). This is a feature of webpack that will automatically reload the app whenever the source code changes.

To enable HMR:

  1. Navigate to an app via the Your apps.

  2. Select Configure your app.

  3. Copy the value from the App origin field. This value is unique to each app and cannot be customized.

  4. In the starter kit's directory, open the .env file.

  5. Set the CANVA_APP_ORIGIN environment variable to the value copied from the App origin field:

    CANVA_APP_ORIGIN=# YOUR APP ORIGIN GOES HERE
    bash
  6. Set the CANVA_HMR_ENABLED environment variable to true:

    CANVA_HMR_ENABLED=true
    bash
  7. Restart the local development server.

  8. Reload the app manually to ensure that HMR takes effect.

All changes to the source code will automatically be reflected in the app's iframe.

Although Canva has a desktop app, we recommend previewing apps via the web browser. Previewing apps via the desktop app requires a self-signed SSL certificate, which requires extra work without any meaningful benefit and is not something we actively support.

Canva is extremely popular on mobile devices, so it's important to preview and test your app on them. The local development server on your computer won't be accessible via a mobile device though. The workaround is to upload the app's JavaScript bundle via the App source field so that the code can be loaded from Canva's servers.

  • You can't preview an app outside of the Canva editor. This is because the Apps SDK must be able to send and receive messages to and from the editor.

Once you have an app up and running in the Canva editor, you can start writing code that hooks into the Canva editor by calling APIs exposed by the Apps SDK. To learn how, see Integrating with Canva.