Welcome to your Canva App! ๐
This is a starting point for your app using your chosen template. The complete documentation for the platform is at canva.dev/docs/apps.
Note: This code and documentation assumes some experience with TypeScript and React.
- Node.js
v18
orv20.10.0
- npm
v9
orv10
Note: To make sure you're running the correct version of Node.js, we recommend using a version manager, such as nvm. The .nvmrc file in the root directory of this repo will ensure the correct version is used once you run nvm install
.
npm install
To start the boilerplate's development server, run the following command:
npm start
The server becomes available at http://localhost:8080.
The app's source code is in the src/app.tsx
file.
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:
- Create an app via the Developer Portal.
- Select App 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 Open. (This screen only appears when using an app for the first time.)
The app will appear in the side panel.
Previewing apps in Safari
By default, the development server is not HTTPS-enabled. This is convenient, as there's no need for a security certificate, but it prevents apps from being previewed in Safari.
Why Safari requires the development server to be HTTPS-enabled?
Canva itself is served via HTTPS and most browsers prevent HTTPS pages from loading scripts via non-HTTPS connections. Chrome and Firefox make exceptions for local servers, such as localhost
, but Safari does not, so if you're using Safari, the development server must be HTTPS-enabled.
To learn more, see Loading mixed-content resources.
To preview apps in Safari:
- Start the development server with HTTPS enabled:
# Run the main app
npm start --use-https
# Run an example
npm start <example-name> --use-https
- Navigate to https://localhost:8080.
- Bypass the invalid security certificate warning:
- Click Show details.
- Click Visit website.
- In the Developer Portal, set the app's Development URL to https://localhost:8080.
You need to bypass the invalid security certificate warning every time you start the local server. A similar warning will appear in other browsers (and will need to be bypassed) whenever HTTPS is enabled.
By default, every time you make a change to an app, you have to reload the entire app to see the results of those changes. If you enable Hot Module Replacement (HMR), changes will be reflected without a full reload, which significantly speeds up the development loop.
Note: HMR does not work while running the development server in a Docker container.
To enable HMR:
-
Navigate to an app via the Your apps.
-
Select Configure your app.
-
Copy the value from the App origin field. This value is unique to each app and cannot be customized.
-
In the root directory, open the
.env
file. -
Set the
CANVA_APP_ORIGIN
environment variable to the value copied from the App origin field:CANVA_APP_ORIGIN=# YOUR APP ORIGIN GOES HERE
-
Set the
CANVA_HMR_ENABLED
environment variable totrue
:CANVA_HMR_ENABLED=true
-
Restart the local development server.
-
Reload the app manually to ensure that HMR takes effect.
Some templates provide an example backend. This backend is defined in the template's backend/server.ts
file, automatically starts when the npm start
command is run, and becomes available at http://localhost:3001.
To run templates that have a backend:
-
Navigate to the Your apps page.
-
Copy the ID of an app from the App ID column.
-
In the starter kit's
.env
file, setCANVA_APP_ID
to the ID of the app.For example:
CANVA_APP_ID=AABBccddeeff CANVA_APP_ORIGIN=# CANVA_BACKEND_PORT=3001 CANVA_FRONTEND_PORT=8080 CANVA_BACKEND_HOST=http://localhost:3001 CANVA_HMR_ENABLED=FALSE
-
Start the app:
npm start
The ID of the app must be explicitly defined because it's required to send and verify HTTP requests. If you don't set up the ID in the .env
file, an error will be thrown when attempting to run the example.
If your app has a backend, the URL of the server likely depends on whether it's a development or production build. For example, during development, the backend is probably running on a localhost URL, but once the app's in production, the backend needs to be exposed to the internet.
To more easily customize the URL of the server:
-
Open the
.env
file in the text editor of your choice. -
Set the
CANVA_BACKEND_HOST
environment variable to the URL of the server. -
When sending a request, use
BACKEND_HOST
as the base URL:const response = await fetch(`${BACKEND_HOST}/custom-route`);
Note:
BACKEND_HOST
is a global constant that contains the value of theCANVA_BACKEND_HOST
environment variable. The variable is made available to the app via webpack and does not need to be imported. -
Before bundling the app for production, update
CANVA_BACKEND_HOST
to point to the production backend.
If your app requires authentication with a third party service, your server needs to be exposed via a publicly available URL, so that Canva can send requests to it. This step explains how to do this with ngrok.
Note: ngrok is a useful tool, but it has inherent security risks, such as someone figuring out the URL of your server and accessing proprietary information. Be mindful of the risks, and if you're working as part of an organization, talk to your IT department. You must replace ngrok urls with hosted API endpoints for production apps.
To use ngrok, you'll need to do the following:
-
Sign up for a ngrok account at https://ngrok.com/.
-
Locate your ngrok authtoken.
-
Set an environment variable for your authtoken, using the command line. Replace
<YOUR_AUTH_TOKEN>
with your actual ngrok authtoken:For macOS and Linux:
export NGROK_AUTHTOKEN=<YOUR_AUTH_TOKEN>
For Windows PowerShell:
$Env:NGROK_AUTHTOKEN = "<YOUR_AUTH_TOKEN>"
This environment variable is available for the current terminal session, so the command must be re-run for each new session. Alternatively, you can add the variable to your terminal's default parameters.
These steps demonstrate how to start the local development server with ngrok.
From your app's root directory
-
Stop any running scripts, and run the following command to launch the backend and frontend development servers. The
--ngrok
parameter exposes the backend server via a publicly accessible URL.npm start --ngrok
-
After ngrok is running, copy your ngrok url (e.g.
https://0000-0000.ngrok-free.app
) to the clipboard.- Go to your app in the Developer Portal.
- Navigate to the "Add authentication" section of your app.
- Check "This app requires authentication"
- In the "Redirect URL" text box, enter your ngrok url followed by
/redirect-url
e.g.https://0000-0000.ngrok-free.app/redirect-url
- In the "Redirect URL" text box, enter your ngrok url followed by
/
e.g.https://0000-0000.ngrok-free.app/
Note: Your ngrok URL changes each time you restart ngrok. Keep these fields up to date to ensure your example authentication step will run.
-
Make sure the app is authenticating users by making the following changes:
-
Replace
router.post("/resources/find", async (req, res) => {
with
router.post("/api/resources/find", async (req, res) => {
in ./backend/routers/auth.ts. Adding
/api/
to the route ensures the JWT middleware authenticates requests. -
Replace
const url = new URL(`${BACKEND_HOST}/resources/find`);
with
const url = new URL(`${BACKEND_HOST}/api/resources/find`);
in ./adapter.ts
-
Comment out these lines in ./app.tsx
// Comment this next line out for production apps setAuthState("authenticated");
-
-
Navigate to your app at
https://www.canva.com/developers/apps
, and click Preview to preview the app.- A new screen will appear asking if you want to authenticate. Press Connect to start the authentication flow.
- A ngrok screen may appear. If it does, select Visit Site
- An authentication popup will appear. For the username, enter
username
, and for the password enterpassword
. - If successful, you will be redirected back to your app.
-
You can now modify the
/redirect-url
function inserver.ts
to authenticate with your third-party asset manager, and/api/resources/find
to pull assets from your third-party asset manager.See
https://www.canva.dev/docs/apps/authenticating-users/
for more details.
This template captures best practices for improving user experience in your application.
In this template, we've set up state management using React Context
. It's just one way to do it, not a strict rule. If your app gets more complicated, you might want to check out other options like Redux
or MobX
.
As your application evolves, you may find the need for routing to manage multiple views or pages. In this template, we've integrated React Router to illustrate how routing can facilitate seamless navigation between various components.
Creating AI assets can be time-consuming, often resulting in users facing extended waiting periods. Incorporating placeholders, a loading bar, and a message indicating the expected wait time can help alleviate the perceived wait time. We highly encourage adopting this approach and customizing it to suit your specific use case.
In this template, we've included a basic obscenity filter to stop users from creating offensive or harmful content. However, you might need additional filters or checks after content generation to ensure it meets your standards.
This template includes a simple Express server as a sample backend. Please note that this server is not production-ready, and we advise using it solely for instructional purposes to demonstrate API calls.
This template illustrates how your API could return thumbnails and demonstrates their usage within the code. Thumbnails play a crucial role in optimizing image uploads and previews by providing quick visual feedback and reducing load times.