Previewing apps

When you have set up your app, for example after running through the Quickstart, you can preview how it looks and behaves in the Canva editor.

There are two ways to preview your app:

• Generate a JavaScript bundle and upload it using 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.

Apps created with the starter kit or with a template through the Canva CLI both use @canva/app-scripts to run a local development server, with no configuration required. The local server exposes the app's source code through a URL that can be shared with Canva.

To start the local development server:

1. Change into the app's folder:

   cd my-new-app

   SHELL

   Copy

2. Run the following command to start your app:

   canva apps start

   SHELL

   Copy

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

By default, the development server doesn't 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:

   canva apps start --use-https

   SHELL

   Copy

2. Navigate to https://localhost:8080⁠(opens in a new tab or window).

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.

1. On the app's Inside Canva page, set Code upload > App source > Development URL to the address of your local development server.

   The URL must point directly to a standalone JavaScript file. This field exists only for development: you can't submit an app for review while it holds a value.

2. Click Preview.

   The app opens in a new tab. Apps use the Design Editor intent by default; if your app implements another intent, or more than one, choose which to preview under Preview options > Choose an intent, beside Preview.

3. The first time you open an app you have to connect it. Click Open, and the app loads in the iframe.

If you're using Google Chrome, click Allow when prompted by your browser to allow local network access.

If you make a change to the app — for example, by editing the src/app.tsx file — that change isn't 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 is only visible if the app is under active development, in the Draft state. It's not visible once the app has been submitted for review or released.

• 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 lets @canva/app-scripts automatically reload the app in place whenever the source code changes, without a full page refresh.

To enable HMR:

1. Navigate to an app using the Your apps⁠(opens in a new tab or window) page.

2. Go to Inside Canva > Code upload, and in the App identifiers panel select the .env file tab.

3. Copy the .env file contents.

4. Paste the contents into your app's .env file. For example:

   CANVA_APP_ID=AABBccddeeff
   CANVA_APP_ORIGIN=https://app-aabbccddeeff.canva-apps.com
   CANVA_HMR_ENABLED=TRUE

   BASH

   Copy

5. Restart the local development server.

6. 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⁠(opens in a new tab or window), we recommend previewing apps using the web browser. Previewing apps using the desktop app requires a self-signed SSL certificate, which requires extra work without any meaningful benefit and isn't 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 from a mobile device though. The workaround is to upload the app's JavaScript bundle using 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 Canva Developers SDK must be able to send and receive messages to and from the editor.

Chrome and other Chromium-based browsers require explicit permission to access local development servers for security reasons.

When you first preview your app, Chrome will display a permission prompt in the address bar. To grant access, click Allow.

If you have previously denied access to localhost in Chrome, you will see a crossed out network icon. If this is the case, you can still grant it:

1. Click the permission prompt icon in the address bar.
2. Toggle local network access to "on" to grant permission.

The permission is remembered for the current site during your session.

If your app isn't loading in the Canva editor:

• Verify the development server is running: Check that canva apps start is running without errors.
• Check the Development URL: Ensure the URL in the Developer Portal matches your local server (for example, http://localhost:8080).
• Check browser console: Look for error messages that might indicate the issue.
• Clear browser cache: Sometimes cached content can cause loading issues.

If changes aren't automatically reflected:

• Verify CANVA_HMR_ENABLED=TRUE is set in your .env file.
• Restart the development server after updating the .env file.
• Manually reload the app once after enabling HMR.
• Check that the .env file contains the correct CANVA_APP_ID and CANVA_APP_ORIGIN.

If changes aren't visible after reloading:

• Verify you're editing the correct file in your source code.
• Check that the development server detected the file change (watch for console output).
• Try a hard refresh in the browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows).
• Restart the development server.

If you see security warnings when using HTTPS:

• This is expected behavior with self-signed certificates.
• You must bypass the warning each time you start the server.
• Consider using HTTP for development (use HTTPS only if required for Safari).

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 Developers SDK. To learn how, see How apps work in Canva.