@canva/cli 1.14.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canva/cli",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "The official Canva CLI.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Canva Pty Ltd.",

package/templates/base/backend/base_backend/create.ts

@@ -1,4 +1,5 @@
 /* eslint-disable no-console */
+import { TokenVerificationError } from "@canva/app-middleware";
 import debug from "debug";
 import express from "express";
 import type { NextFunction, Request, Response } from "express";
@@ -63,6 +64,15 @@ export function createBaseServer(router: express.Router): BaseServer {
 
   // default error handler
   app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
+    // Handle authentication errors from @canva/app-middleware
+    if (err instanceof TokenVerificationError) {
+      res.status(err.statusCode).json({
+        error: err.code,
+        message: err.message,
+      });
+      return;
+    }
+
     console.error(err.stack);
     res.status(500).send({
       error: "something went wrong",

package/templates/base/backend/routers/auth.ts

@@ -1,11 +1,11 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion -- user is guaranteed by verifyToken middleware */
+import { tokenExtractors, user } from "@canva/app-middleware/express";
 import chalk from "chalk";
 import cookieParser from "cookie-parser";
 import crypto from "crypto";
 import "dotenv/config";
 import express from "express";
 import basicAuth from "express-basic-auth";
-import { createJwtMiddleware } from "../../utils/backend/jwt_middleware";
-import { getTokenFromQueryString } from "../../utils/backend/jwt_middleware/jwt_middleware";
 import { JSONFileDatabase } from "../database/database";
 
 /**
@@ -95,7 +95,10 @@ export const createAuthRouter = () => {
      * Use a JSON Web Token (JWT) to verify incoming requests. The JWT is
      * extracted from the `canva_user_token` parameter.
      */
-    createJwtMiddleware(APP_ID, getTokenFromQueryString),
+    user.verifyToken({
+      appId: APP_ID,
+      tokenExtractor: tokenExtractors.fromQuery("canva_user_token"),
+    }),
     /**
      * Warning: For demonstration purposes, we're using basic authentication and
      * hard- coding a username and password. This is not a production-ready
@@ -155,8 +158,8 @@ export const createAuthRouter = () => {
         return failureResponse();
       }
 
-      // Get the userId from JWT middleware
-      const { userId } = req.canva;
+      // Get the userId from user object in the request context
+      const { userId } = req.canva.user!;
 
       // Load the database
       const data = await db.read();
@@ -182,7 +185,7 @@ export const createAuthRouter = () => {
    * TODO: Add this middleware to all routes that will receive requests from
    * your app.
    */
-  const jwtMiddleware = createJwtMiddleware(APP_ID);
+  const jwtMiddleware = user.verifyToken({ appId: APP_ID });
 
   /**
    * This endpoint is called when a user disconnects an app from their account.
@@ -197,8 +200,8 @@ export const createAuthRouter = () => {
    * Developer Portal. Localhost addresses will not work to test this endpoint.
    */
   router.post("/configuration/delete", jwtMiddleware, async (req, res) => {
-    // Get the userId from JWT middleware
-    const { userId } = req.canva;
+    // Get the userId from user object in the request context
+    const { userId } = req.canva.user!;
 
     // Load the database
     const data = await db.read();
@@ -227,7 +230,7 @@ export const createAuthRouter = () => {
     const data = await db.read();
 
     // Check if the user is authenticated
-    const isAuthenticated = data.users.includes(req.canva.userId);
+    const isAuthenticated = data.users.includes(req.canva.user!.userId);
 
     // Return the authentication status
     res.send({

package/templates/base/package.json

@@ -8,11 +8,11 @@
   "dependencies": {
     "@canva/app-hooks": "^0.0.0-beta.4",
     "@canva/app-i18n-kit": "^1.2.0",
-    "@canva/app-ui-kit": "^5.4.0",
+    "@canva/app-ui-kit": "^5.5.0",
     "@canva/asset": "^2.3.0",
     "@canva/design": "^2.7.5",
-    "@canva/error": "^2.1.0",
-    "@canva/platform": "^2.2.0",
+    "@canva/error": "^2.2.0",
+    "@canva/platform": "^2.2.1",
     "@canva/user": "^2.1.2",
     "cookie-parser": "1.4.7",
     "react": "^19.2.3",

package/templates/content_publisher/README.md

@@ -0,0 +1,58 @@
+# Content Publisher Template
+
+## Overview
+
+This template provides a minimal starting point for building a content publisher app. It demonstrates the basic structure and key concepts of the Content Publisher intent, including:
+
+- Implementing the Content Publisher intent with all required functions
+- Rendering a settings UI where users configure publishing options
+- Rendering a preview UI that shows how content will appear after publishing
+- Defining output types and media slot specifications
+- Handling publish operations (with placeholder implementation)
+
+This template focuses on the intent structure and UI patterns. You'll need to add your own platform integration, including authentication and API calls to your publishing service.
+
+## What's Included
+
+### Content Publisher Intent Structure
+
+The template implements all four required functions:
+
+- `renderSettingsUi`: Renders a simple settings form with a caption input field
+- `renderPreviewUi`: Displays a mock social media post preview
+- `getPublishConfiguration`: Defines a "Feed Post" output type with image specifications
+- `publishContent`: Placeholder function that returns mock success response
+
+### UI Components
+
+- **Settings UI** (`settings_ui.tsx`): A form using the App UI Kit with a caption field and validation
+- **Preview UI** (`preview_ui.tsx`): A social media post preview showing how the published content will look
+
+### App UI Kit
+
+The App UI Kit is a React-based component library designed for creating apps that emulate Canva's look and feel. We strongly recommend using the App UI Kit if you're planning to release an app to the public, as this makes it easier to comply with our [design guidelines](https://www.canva.dev/docs/apps/design-guidelines/).
+
+This template uses the App UI Kit for both the settings and preview UIs to demonstrate common patterns. The preview UI is more flexible in production and can be customized to match your target platform's design system.
+
+## Getting Started
+
+### 0. Set up your app
+
+- If not already handled by the Canva CLI, you need to create an app via the [Developer Portal](https://www.canva.com/developers/apps).
+- On the **Intents** page, enable the `Content Publisher` intent
+
+### 1. Run the template
+
+- Run `npm start` to start the development server
+- Click **Preview URL** in the terminal or **Preview** in the [Developer Portal](https://www.canva.com/developers/apps) to view the app in the Canva editor
+- Try entering a caption and viewing the preview
+
+### 2. Customize for your platform
+
+To integrate with your publishing platform, you'll need to:
+
+- **Add authentication**: [Implement OAuth](https://www.canva.dev/docs/apps/authenticating-users/oauth/) or your authentication method to connect user accounts
+- **Customize settings**: Modify `settings_ui.tsx` to collect platform-specific publishing options
+- **Update preview**: Modify `preview_ui.tsx` to match your platform's post appearance
+- **Configure output types**: Update `getPublishConfiguration` in `index.tsx` to define your supported formats and media requirements
+- **Implement publishing**: Replace the placeholder in `publishContent` with actual API calls to your platform

package/templates/content_publisher/canva-app.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://www.canva.dev/schemas/app/v1/manifest-schema.json",
+  "manifest_schema_version": 1,
+  "runtime": {
+    "permissions": [
+      {
+        "name": "canva:design:content:read",
+        "type": "mandatory"
+      }
+    ]
+  },
+  "intent": {
+    "content_publisher": {
+      "enrolled": true
+    }
+  }
+}

package/templates/content_publisher/declarations/declarations.d.ts

@@ -0,0 +1,29 @@
+declare module "*.css" {
+  const styles: { [className: string]: string };
+  export = styles;
+}
+
+declare module "*.jpg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.jpeg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.png" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.svg" {
+  const content: React.FunctionComponent<{
+    size?: "tiny" | "small" | "medium" | "large";
+    className?: string;
+  }>;
+  export default content;
+}
+
+declare const BACKEND_HOST: string;

package/templates/content_publisher/eslint.config.mjs

@@ -0,0 +1,14 @@
+import canvaPlugin from "@canva/app-eslint-plugin";
+
+export default [
+  {
+    ignores: [
+      "**/node_modules/",
+      "**/dist",
+      "**/*.d.ts",
+      "**/*.d.tsx",
+      "**/*.config.*",
+    ],
+  },
+  ...canvaPlugin.configs.apps,
+];

package/templates/content_publisher/package.json

@@ -0,0 +1,90 @@
+{
+  "private": true,
+  "name": "content_publisher",
+  "description": "A Canva Content Publisher App",
+  "scripts": {
+    "extract": "formatjs extract \"src/**/*.{ts,tsx}\" --out-file dist/messages_en.json",
+    "build": "webpack --config webpack.config.ts --mode production && npm run extract",
+    "format": "prettier '**/*.{css,ts,tsx}' --no-config --write",
+    "format:check": "prettier '**/*.{css,ts,tsx}' --no-config --check --ignore-path",
+    "format:file": "prettier $1 --no-config --write",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "lint:types": "tsc",
+    "start": "ts-node ./scripts/start/start.ts",
+    "start:preview": "npm run start -- --preview",
+    "test": "jest --no-cache",
+    "test:watch": "jest --watchAll",
+    "test:update": "npm run test -- -u",
+    "postinstall": "ts-node ./scripts/copy_env.ts"
+  },
+  "dependencies": {
+    "@canva/app-hooks": "^0.0.0-beta.4",
+    "@canva/app-i18n-kit": "^1.2.0",
+    "@canva/app-ui-kit": "^5.5.0",
+    "@canva/asset": "^2.3.0",
+    "@canva/design": "^2.7.5",
+    "@canva/error": "^2.2.0",
+    "@canva/intents": "^2.0.2-beta.3",
+    "@canva/platform": "^2.2.1",
+    "@canva/user": "^2.1.2",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "react-intl": "^7.1.11"
+  },
+  "devDependencies": {
+    "@canva/app-eslint-plugin": "^1.0.0-beta.7",
+    "@canva/cli": ">= 0.0.1-beta.13",
+    "@formatjs/cli": "6.7.2",
+    "@formatjs/ts-transformer": "3.14.0",
+    "@ngrok/ngrok": "1.5.2",
+    "@pmmmwh/react-refresh-webpack-plugin": "0.6.1",
+    "@svgr/webpack": "8.1.0",
+    "@testing-library/react": "16.3.0",
+    "@types/debug": "4.1.12",
+    "@types/express": "4.17.21",
+    "@types/jest": "29.5.14",
+    "@types/jsonwebtoken": "9.0.10",
+    "@types/node": "20.19.2",
+    "@types/node-fetch": "2.6.13",
+    "@types/node-forge": "1.3.14",
+    "@types/nodemon": "1.19.6",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.1",
+    "@types/webpack-env": "1.18.8",
+    "chalk": "4.1.2",
+    "cli-table3": "0.6.5",
+    "css-loader": "7.1.2",
+    "css-modules-typescript-loader": "4.0.1",
+    "cssnano": "7.1.1",
+    "debug": "4.4.1",
+    "dotenv": "16.6.0",
+    "express": "4.22.1",
+    "express-basic-auth": "1.2.1",
+    "jest": "29.7.0",
+    "jest-css-modules-transform": "4.4.2",
+    "jest-environment-jsdom": "29.7.0",
+    "jsonwebtoken": "9.0.3",
+    "jwks-rsa": "3.2.0",
+    "mini-css-extract-plugin": "2.9.4",
+    "node-fetch": "3.3.2",
+    "node-forge": "1.3.2",
+    "nodemon": "3.0.1",
+    "open": "8.4.2",
+    "postcss-loader": "8.1.1",
+    "prettier": "3.6.2",
+    "react-refresh": "0.17.0",
+    "style-loader": "4.0.0",
+    "terser-webpack-plugin": "5.3.14",
+    "tree-kill": "1.2.2",
+    "ts-jest": "29.4.1",
+    "ts-loader": "9.5.4",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.2",
+    "url-loader": "4.1.1",
+    "webpack": "5.99.9",
+    "webpack-cli": "6.0.1",
+    "webpack-dev-server": "5.2.2",
+    "yargs": "17.7.2"
+  }
+}

package/templates/content_publisher/scripts/copy_env.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import fs from "fs";
+import path from "path";
+
+const envPath = path.resolve(__dirname, "..", ".env");
+const templatePath = path.resolve(__dirname, "..", ".env.template");
+
+if (!fs.existsSync(templatePath)) {
+  console.warn(".env.template file does not exist, skipping copy of .env file");
+} else if (!fs.existsSync(envPath)) {
+  fs.copyFileSync(templatePath, envPath);
+}

package/templates/content_publisher/scripts/ssl/ssl.ts

@@ -0,0 +1,131 @@
+import crypto from "crypto";
+import fs from "fs/promises";
+import { pki } from "node-forge";
+import path from "path";
+
+const SSL_CERT_DIR = path.resolve(process.cwd(), "..", "..", ".ssl");
+const CERT_FILE = path.resolve(SSL_CERT_DIR, "certificate.pem");
+const KEY_FILE = path.resolve(SSL_CERT_DIR, "private-key.pem");
+
+export interface Certificate {
+  keyFile: string;
+  certFile: string;
+}
+
+const CERT_ATTRS: { name: string; value: string }[] = [
+  {
+    name: "commonName",
+    value: "localhost",
+  },
+  {
+    name: "countryName",
+    value: "AU",
+  },
+  {
+    name: "stateOrProvinceName",
+    value: "New South Wales",
+  },
+  {
+    name: "localityName",
+    value: "Sydney",
+  },
+  {
+    name: "organizationName",
+    value: "Test",
+  },
+  {
+    name: "organizationalUnitName",
+    value: "Test",
+  },
+];
+
+const generateRsaKeys = async (): Promise<{
+  publicKey: string;
+  privateKey: string;
+}> =>
+  new Promise((resolve, reject) => {
+    crypto.generateKeyPair(
+      "rsa",
+      {
+        modulusLength: 2096,
+        publicKeyEncoding: {
+          type: "spki",
+          format: "pem",
+        },
+        privateKeyEncoding: {
+          type: "pkcs8",
+          format: "pem",
+        },
+      },
+      (err, publicKey, privateKey) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve({ publicKey, privateKey });
+        }
+      },
+    );
+  });
+
+const generateCertificate = (opts: {
+  privateKey: string;
+  publicKey: string;
+}): string => {
+  const privateKey = pki.privateKeyFromPem(opts.privateKey);
+  const publicKey = pki.publicKeyFromPem(opts.publicKey);
+
+  const cert = pki.createCertificate();
+
+  cert.publicKey = publicKey;
+  cert.serialNumber = "01";
+  cert.validity.notBefore = new Date();
+  cert.validity.notAfter = new Date();
+  cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
+
+  cert.setSubject(CERT_ATTRS);
+  cert.setIssuer(CERT_ATTRS);
+
+  // the actual certificate signing
+  cert.sign(privateKey);
+
+  // now convert the Forge certificate to PEM format
+  return pki.certificateToPem(cert);
+};
+
+const writeCertFiles = async (opts: {
+  cert: string;
+  privateKey: string;
+}): Promise<void> => {
+  const { cert, privateKey } = opts;
+
+  await fs.mkdir(SSL_CERT_DIR, { recursive: true });
+  await Promise.all([
+    fs.writeFile(CERT_FILE, cert, { encoding: "utf8" }),
+    fs.writeFile(KEY_FILE, privateKey, { encoding: "utf8" }),
+  ]);
+};
+
+const cerfFilesExist = async (): Promise<boolean> => {
+  try {
+    await Promise.all([
+      fs.access(CERT_FILE, fs.constants.R_OK | fs.constants.W_OK),
+      fs.access(KEY_FILE, fs.constants.R_OK | fs.constants.W_OK),
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const createOrRetrieveCertificate = async (): Promise<Certificate> => {
+  if (!(await cerfFilesExist())) {
+    const keys = await generateRsaKeys();
+    const cert = generateCertificate(keys);
+    await writeCertFiles({ cert, privateKey: keys.privateKey });
+  }
+
+  return {
+    certFile: CERT_FILE,
+    keyFile: KEY_FILE,
+  };
+};

package/templates/content_publisher/scripts/start/app_runner.ts

@@ -0,0 +1,223 @@
+/* eslint-disable no-console */
+import { generatePreviewUrl } from "@canva/cli";
+import ngrok from "@ngrok/ngrok";
+import chalk from "chalk";
+import Table from "cli-table3";
+import nodemon from "nodemon";
+import open from "open";
+import os from "os";
+import webpack from "webpack";
+import WebpackDevServer from "webpack-dev-server";
+import { buildConfig } from "../../webpack.config";
+import type { Certificate } from "../ssl/ssl";
+import { createOrRetrieveCertificate } from "../ssl/ssl";
+import type { Context } from "./context";
+
+export const infoChalk = chalk.blue.bold;
+export const warnChalk = chalk.bgYellow.bold;
+export const errorChalk = chalk.bgRed.bold;
+export const highlightChalk = chalk.greenBright.bold;
+export const linkChalk = chalk.cyan;
+
+/**
+ * Returns the appropriate modifier key text based on the user's operating system.
+ * @returns "cmd" for macOS, "ctrl" for Windows and Linux
+ */
+export function getModifierKey(): string {
+  const platform = os.platform();
+  switch (platform) {
+    case "darwin": // macOS
+      return "cmd";
+    case "win32": // Windows
+      return "ctrl";
+    default: // Linux and others
+      return "ctrl";
+  }
+}
+
+export class AppRunner {
+  async run(ctx: Context) {
+    console.log(
+      infoChalk("Info:"),
+      `Starting development server for ${highlightChalk(ctx.entryDir)}\n`,
+    );
+
+    if (!ctx.hmrEnabled) {
+      console.log(
+        `${infoChalk(
+          "Note:",
+        )} Hot Module Replacement (HMR) not enabled. To enable it, please refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )}\n`,
+      );
+    }
+
+    let cert: Certificate | undefined;
+    if (ctx.httpsEnabled) {
+      try {
+        cert = await createOrRetrieveCertificate();
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          "Unable to generate SSL certificate.",
+        );
+        throw err;
+      }
+    }
+
+    const table = new Table({
+      colWidths: [30, 80],
+      wordWrap: true,
+      wrapOnWordBoundary: true,
+    });
+
+    const server = await this.runWebpackDevServer(ctx, table, cert);
+
+    await this.maybeRunBackendServer(ctx, table, cert, server);
+
+    await this.generateAndOpenPreviewUrl(ctx.openPreview, table);
+
+    console.log(table.toString(), "\n");
+
+    console.log(
+      `${infoChalk(
+        "Note:",
+      )} For instructions on how to set up the app via the Developer Portal, see the ${highlightChalk(
+        "README.md",
+      )}.\n`,
+    );
+  }
+
+  private readonly maybeRunBackendServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+    webpackDevServer: WebpackDevServer,
+  ) => {
+    if (!ctx.developerBackendEntryPath) {
+      return;
+    }
+
+    // App ID must be set when running a backend example
+    if (!ctx.appId) {
+      console.log(
+        errorChalk("Error:"),
+        `'CANVA_APP_ID' environment variable is undefined. Refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )} on starting a backend example.`,
+      );
+      throw new Error("'CANVA_APP_ID' env variable not set.");
+    }
+
+    await new Promise((resolve) => {
+      const nodemonServer = nodemon({
+        script: ctx.developerBackendEntryPath,
+        ext: "ts",
+        env: {
+          SHOULD_ENABLE_HTTPS: ctx.httpsEnabled,
+          HTTPS_CERT_FILE: cert?.certFile || "",
+          HTTPS_KEY_FILE: cert?.keyFile || "",
+        },
+      });
+
+      nodemonServer.on("start", resolve);
+
+      nodemonServer.on("crash", async () => {
+        console.log(errorChalk("Shutting down local server.\n"));
+
+        await webpackDevServer.stop();
+        process.exit(1);
+      });
+    });
+
+    if (ctx.ngrokEnabled) {
+      console.log(
+        warnChalk("Warning:"),
+        `ngrok exposes a local port via a public URL. Be mindful of what's exposed and shut down the server when it's not in use.\n`,
+      );
+    }
+
+    let url = ctx.backendUrl;
+    if (ctx.ngrokEnabled) {
+      try {
+        const ngrokListener = await ngrok.forward({
+          addr: ctx.backendPort,
+          // requires an `NGROK_AUTHTOKEN` env var to be set
+          authtoken_from_env: true,
+        });
+        url = ngrokListener.url() ?? url;
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          `Unable to start ngrok server: ${err}`,
+        );
+      }
+    }
+
+    table.push(["Base URL (Backend)", linkChalk(url)]);
+  };
+
+  private readonly runWebpackDevServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+  ): Promise<WebpackDevServer> => {
+    const runtimeWebpackConfig = buildConfig({
+      appEntry: ctx.frontendEntryPath,
+      backendHost: ctx.backendHost,
+      devConfig: {
+        port: ctx.frontendPort,
+        enableHmr: ctx.hmrEnabled,
+        appId: ctx.appId,
+        appOrigin: ctx.appOrigin,
+        enableHttps: ctx.httpsEnabled,
+        ...cert,
+      },
+    });
+
+    const compiler = webpack(runtimeWebpackConfig);
+    const server = new WebpackDevServer(
+      runtimeWebpackConfig.devServer,
+      compiler,
+    );
+    await server.start();
+
+    table.push(["Development URL (Frontend)", linkChalk(ctx.frontendUrl)]);
+
+    return server;
+  };
+
+  /**
+   * Calls the Canva CLI to generate a preview URL for the app
+   */
+  private readonly generateAndOpenPreviewUrl = async (
+    openPreview: boolean,
+    table: Table.Table,
+  ) => {
+    const previewCellHeader = { content: "Preview your app in Canva" };
+
+    const generatePreviewResult = await generatePreviewUrl();
+
+    if (!generatePreviewResult.success) {
+      table.push([
+        previewCellHeader,
+        { content: warnChalk(generatePreviewResult.message) },
+      ]);
+      return;
+    }
+
+    const modifierKey = getModifierKey();
+
+    table.push([
+      previewCellHeader,
+      {
+        content: `Preview URL (${modifierKey} + click)`,
+        href: generatePreviewResult.data,
+      },
+    ]);
+
+    if (openPreview) {
+      open(generatePreviewResult.data);
+    }
+  };
+}