@canva/cli 0.0.1-beta.8 → 1.0.0

package/templates/hello_world/package.json

@@ -4,7 +4,7 @@
   "description": "An empty Canva App",
   "scripts": {
     "extract": "formatjs extract \"src/**/*.{ts,tsx}\" --out-file dist/messages_en.json",
-    "build": "webpack --config webpack.config.cjs --mode production && npm run extract",
+    "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",
@@ -12,72 +12,77 @@
     "lint:fix": "eslint . --fix",
     "lint:types": "tsc",
     "start": "ts-node ./scripts/start/start.ts",
-    "test": "jest --no-cache --passWithNoTests",
+    "start:preview": "npm run start -- --preview",
+    "test": "jest --no-cache",
     "test:watch": "jest --watchAll",
-    "postinstall": "ts-node ./scripts/copy-env.ts"
+    "test:update": "npm run test -- -u",
+    "postinstall": "ts-node ./scripts/copy_env.ts"
   },
   "dependencies": {
-    "@canva/app-i18n-kit": "^1.0.1",
-    "@canva/app-ui-kit": "^4.3.0",
-    "@canva/design": "^2.2.1",
-    "@canva/error": "^2.0.0",
-    "@canva/platform": "^2.0.0",
+    "@canva/app-i18n-kit": "^1.0.3",
+    "@canva/app-ui-kit": "^4.10.0",
+    "@canva/asset": "^2.2.1",
+    "@canva/design": "^2.7.2",
+    "@canva/error": "^2.1.0",
+    "@canva/platform": "^2.2.0",
+    "@canva/user": "^2.1.1",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "react-intl": "6.8.7"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "3.1.0",
-    "@eslint/js": "9.14.0",
-    "@formatjs/cli": "6.3.8",
-    "@formatjs/ts-transformer": "3.13.22",
-    "@ngrok/ngrok": "1.4.1",
+    "@canva/app-eslint-plugin": "^1.0.0-beta.3",
+    "@canva/cli": ">= 0.0.1-beta.13",
+    "@formatjs/cli": "6.7.2",
+    "@formatjs/ts-transformer": "3.14.0",
+    "@ngrok/ngrok": "1.5.1",
+    "@pmmmwh/react-refresh-webpack-plugin": "0.6.1",
     "@svgr/webpack": "8.1.0",
+    "@testing-library/react": "16.3.0",
     "@types/express": "4.17.21",
-    "@types/express-serve-static-core": "4.19.6",
+    "@types/express-serve-static-core": "5.0.6",
     "@types/jest": "29.5.14",
-    "@types/jsonwebtoken": "9.0.7",
-    "@types/node": "20.10.0",
-    "@types/node-fetch": "2.6.11",
+    "@types/jsonwebtoken": "9.0.10",
+    "@types/node": "20.19.2",
+    "@types/node-fetch": "2.6.12",
     "@types/node-forge": "1.3.11",
     "@types/nodemon": "1.19.6",
     "@types/react": "18.3.12",
     "@types/react-dom": "18.3.1",
-    "@types/webpack-env": "1.18.5",
-    "@typescript-eslint/eslint-plugin": "8.13.0",
-    "@typescript-eslint/parser": "8.13.0",
+    "@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.0.6",
-    "debug": "4.3.7",
-    "dotenv": "16.4.5",
-    "eslint": "9.14.0",
-    "eslint-plugin-formatjs": "5.2.2",
-    "eslint-plugin-jest": "28.9.0",
-    "eslint-plugin-react": "7.37.2",
-    "express": "4.21.1",
+    "cssnano": "7.0.7",
+    "debug": "4.4.1",
+    "dotenv": "16.6.0",
+    "express": "4.21.2",
     "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.2",
-    "jwks-rsa": "3.1.0",
+    "jwks-rsa": "3.2.0",
     "mini-css-extract-plugin": "2.9.2",
     "node-fetch": "3.3.2",
     "node-forge": "1.3.1",
     "nodemon": "3.0.1",
+    "open": "8.4.2",
     "postcss-loader": "8.1.1",
-    "prettier": "3.3.3",
+    "prettier": "3.6.2",
+    "react-refresh": "0.17.0",
     "style-loader": "4.0.0",
-    "terser-webpack-plugin": "5.3.10",
-    "ts-jest": "29.2.5",
-    "ts-loader": "9.5.1",
+    "terser-webpack-plugin": "5.3.14",
+    "tree-kill": "1.2.2",
+    "ts-jest": "29.4.0",
+    "ts-loader": "9.5.2",
     "ts-node": "10.9.2",
-    "typescript": "5.5.4",
+    "typescript": "5.8.2",
     "url-loader": "4.1.1",
-    "webpack": "5.96.1",
-    "webpack-cli": "5.1.4",
-    "webpack-dev-server": "5.1.0",
+    "webpack": "5.99.9",
+    "webpack-cli": "6.0.1",
+    "webpack-dev-server": "5.2.2",
     "yargs": "17.7.2"
   }
 }

package/templates/hello_world/scripts/copy_env.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import * as fs from "fs";
+import * as path from "path";
+
+const envPath = path.resolve(__dirname, "..", ".env");
+const templatePath = path.resolve(__dirname, "..", ".env.template");
+
+if (!fs.existsSync(envPath)) {
+  fs.copyFileSync(templatePath, envPath);
+}

package/templates/hello_world/scripts/ssl/ssl.ts

@@ -1,7 +1,7 @@
 import * as crypto from "crypto";
+import * as fs from "fs/promises";
 import { pki } from "node-forge";
 import * as path from "path";
-import * as fs from "fs/promises";
 
 const SSL_CERT_DIR = path.resolve(process.cwd(), "..", "..", ".ssl");
 const CERT_FILE = path.resolve(SSL_CERT_DIR, "certificate.pem");

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

@@ -1,14 +1,16 @@
 /* eslint-disable no-console */
-import type { Context } from "./context";
-import * as chalk from "chalk";
-import { buildConfig } from "../../webpack.config.cjs";
+import { generatePreviewUrl } from "@canva/cli";
 import * as ngrok from "@ngrok/ngrok";
-import * as nodemon from "nodemon";
+import * as chalk from "chalk";
 import * as Table from "cli-table3";
+import * as nodemon from "nodemon";
+import * as open from "open";
 import * as webpack from "webpack";
 import * as 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;
@@ -46,12 +48,18 @@ export class AppRunner {
       }
     }
 
-    const table = new Table();
+    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(
@@ -161,4 +169,33 @@ export class AppRunner {
 
     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;
+    }
+
+    table.push([
+      previewCellHeader,
+      { content: "Preview URL", href: generatePreviewResult.data },
+    ]);
+
+    if (openPreview) {
+      open(generatePreviewResult.data);
+    }
+  };
 }

package/templates/hello_world/scripts/start/context.ts

@@ -3,8 +3,10 @@ import * as path from "path";
 
 interface CliArgs {
   example?: string;
-  useHttps?: boolean;
-  ngrok?: boolean;
+  useHttps: boolean;
+  ngrok: boolean;
+  preview: boolean;
+  overrideFrontendPort?: number;
 }
 
 interface EnvVars {
@@ -45,7 +47,7 @@ export class Context {
   }
 
   get ngrokEnabled() {
-    return !!this.args.ngrok;
+    return this.args.ngrok;
   }
 
   get hmrEnabled() {
@@ -53,7 +55,7 @@ export class Context {
   }
 
   get httpsEnabled() {
-    return !!this.args.useHttps;
+    return this.args.useHttps;
   }
 
   get frontendEntryPath() {
@@ -69,11 +71,11 @@ export class Context {
   }
 
   get frontendUrl() {
-    return `${this.protocol}://localhost:${this.envVars.frontendPort}`;
+    return `${this.protocol}://localhost:${this.frontendPort}`;
   }
 
   get frontendPort() {
-    return this.envVars.frontendPort;
+    return this.args.overrideFrontendPort || this.envVars.frontendPort;
   }
 
   get developerBackendEntryPath(): string | undefined {
@@ -117,6 +119,10 @@ export class Context {
     return this.envVars.appId;
   }
 
+  get openPreview(): boolean {
+    return this.args.preview;
+  }
+
   private get protocol(): "https" | "http" {
     return this.httpsEnabled ? "https" : "http";
   }

package/templates/hello_world/scripts/start/start.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import * as yargs from "yargs";
-import { AppRunner } from "./app_runner";
 import { hideBin } from "yargs/helpers";
+import { AppRunner } from "./app_runner";
 import { Context } from "./context";
 
 const appRunner = new AppRunner();
@@ -23,6 +23,17 @@ yargs(hideBin(process.argv))
     default:
       process.env.npm_config_use_https?.toLocaleLowerCase().trim() === "true",
   })
+  .option("override-frontend-port", {
+    description:
+      "Port to run the local development server on. Overrides the frontend port set in the .env file.",
+    type: "number",
+    alias: "p",
+  })
+  .option("preview", {
+    description: "Open the app in Canva.",
+    type: "boolean",
+    default: false,
+  })
   .command(
     "$0",
     "Starts local development",

package/templates/hello_world/scripts/start/tests/start.tests.ts

@@ -0,0 +1,61 @@
+/* eslint-disable no-console */
+
+import type { ChildProcess } from "child_process";
+import { spawn } from "child_process";
+import * as treeKill from "tree-kill";
+
+describe("start script", () => {
+  let serverProcess: ChildProcess;
+
+  afterEach(() => {
+    if (serverProcess?.pid && !serverProcess.exitCode) {
+      treeKill(serverProcess.pid);
+    }
+  });
+
+  it("should execute 'npm run start' and start a dev server", async () => {
+    const testServerPort = 8089;
+    serverProcess = await spawn(
+      `npm run start -- -p ${testServerPort} --no-preview`,
+      {
+        shell: true,
+      },
+    );
+
+    if (!serverProcess.pid) {
+      throw new Error("Unable to start server");
+    }
+
+    // wait for the server to start and collect output until it reports the running URL
+    let output = "";
+    await new Promise<void>((resolve, reject) => {
+      serverProcess.stdout?.on("data", (data) => {
+        output += data.toString();
+        if (output.includes("Development URL")) {
+          resolve();
+        }
+      });
+
+      serverProcess.stderr?.on("data", (data) => {
+        console.error("Server process error: ", data.toString());
+        reject();
+      });
+
+      // timeout and fail test if the server hasn't correctly started in 10 seconds
+      setTimeout(() => {
+        if (serverProcess?.pid && !serverProcess.exitCode) {
+          treeKill(serverProcess.pid);
+        }
+        reject(new Error("Test timed out"));
+      }, 10000);
+    });
+
+    // check that the server is running and accessible
+    const expectedServerURL = `http://localhost:${testServerPort}`;
+    expect(output).toContain(expectedServerURL);
+    expect(serverProcess.exitCode).toBeNull();
+
+    // clean up
+    treeKill(serverProcess.pid);
+  }, 15000); // 15 seconds timeout to allow for the server to start
+});

package/templates/hello_world/src/app.tsx

@@ -1,7 +1,10 @@
 import { Button, Rows, Text } from "@canva/app-ui-kit";
+import { requestOpenExternalUrl } from "@canva/platform";
 import { FormattedMessage, useIntl } from "react-intl";
-import * as styles from "styles/components.css";
 import { useAddElement } from "utils/use_add_element";
+import * as styles from "styles/components.css";
+
+export const DOCS_URL = "https://www.canva.dev/docs/apps/";
 
 export const App = () => {
   const addElement = useAddElement();
@@ -13,6 +16,16 @@ export const App = () => {
     });
   };
 
+  const openExternalUrl = async (url: string) => {
+    const response = await requestOpenExternalUrl({
+      url,
+    });
+
+    if (response.status === "aborted") {
+      // user decided not to navigate to the link
+    }
+  };
+
   const intl = useIntl();
 
   return (
@@ -37,6 +50,13 @@ export const App = () => {
               "Button text to do something cool. Creates a new text element when pressed.",
           })}
         </Button>
+        <Button variant="secondary" onClick={() => openExternalUrl(DOCS_URL)}>
+          {intl.formatMessage({
+            defaultMessage: "Open Canva Apps SDK docs",
+            description:
+              "Button text to open Canva Apps SDK docs. Opens an external URL when pressed.",
+          })}
+        </Button>
       </Rows>
     </div>
   );

package/templates/hello_world/src/index.tsx

@@ -1,8 +1,8 @@
+import { AppI18nProvider } from "@canva/app-i18n-kit";
 import { AppUiProvider } from "@canva/app-ui-kit";
 import { createRoot } from "react-dom/client";
 import { App } from "./app";
 import "@canva/app-ui-kit/styles.css";
-import { AppI18nProvider } from "@canva/app-i18n-kit";
 
 const root = createRoot(document.getElementById("root") as Element);
 function render() {

package/templates/hello_world/src/tests/__snapshots__/app.tests.tsx.snap

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Hello World Tests should have a consistent snapshot 1`] = `
+<div>
+  <div
+    class="scrollContainer"
+  >
+    <div
+      class="jv_R6g"
+      style="--NZu1Zw: 16px;"
+    >
+      <p
+        class="aWBg0w aZskFA u16U_g"
+      >
+        To make changes to this app, edit the 
+        <code>
+          src/app.tsx
+        </code>
+         file, then close and reopen the app in the editor to preview the changes.
+      </p>
+      <button
+        class="_5KtATA LQzFZw VgvqkQ _8ERLTg rV61VQ LQzFZw VgvqkQ _4_iekA _3oHQrw j34Zww aqbYPg _3FvZZg"
+        type="button"
+      >
+        <span
+          class="khPe7Q"
+        >
+          Do something cool
+        </span>
+      </button>
+      <button
+        class="_5KtATA LQzFZw VgvqkQ _8ERLTg Z3nT2A LQzFZw VgvqkQ _4_iekA j34Zww aqbYPg _3FvZZg"
+        type="button"
+      >
+        <span
+          class="khPe7Q"
+        >
+          Open Canva Apps SDK docs
+        </span>
+      </button>
+    </div>
+  </div>
+  ,
+</div>
+`;

package/templates/hello_world/src/tests/app.tests.tsx

@@ -0,0 +1,86 @@
+/* eslint-disable formatjs/no-literal-string-in-jsx */
+import { TestAppI18nProvider } from "@canva/app-i18n-kit";
+import { TestAppUiProvider } from "@canva/app-ui-kit";
+import { requestOpenExternalUrl } from "@canva/platform";
+import { fireEvent, render } from "@testing-library/react";
+import type { RenderResult } from "@testing-library/react";
+import React from "react";
+import { useAddElement } from "utils/use_add_element";
+import { App, DOCS_URL } from "../app";
+
+function renderInTestProvider(node: React.ReactNode): RenderResult {
+  return render(
+    // In a test environment, you should wrap your apps in `TestAppI18nProvider` and `TestAppUiProvider`, rather than `AppI18nProvider` and `AppUiProvider`
+    <TestAppI18nProvider>
+      <TestAppUiProvider>{node}</TestAppUiProvider>,
+    </TestAppI18nProvider>,
+  );
+}
+
+jest.mock("utils/use_add_element");
+
+// This test demonstrates how to test code that uses functions from the Canva Apps SDK
+// For more information on testing with the Canva Apps SDK, see https://www.canva.dev/docs/apps/testing/
+describe("Hello World Tests", () => {
+  // Mocking the useAddElement hook
+  const mockAddElement = jest.fn();
+  const mockAddUseElement = jest.mocked(useAddElement);
+  const mockRequestOpenExternalUrl = jest.mocked(requestOpenExternalUrl);
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    mockAddUseElement.mockReturnValue(mockAddElement);
+    mockRequestOpenExternalUrl.mockResolvedValue({ status: "completed" });
+  });
+
+  // this test uses a mock in place of the useAddElement hook
+  it("should add a text element when the button is clicked", () => {
+    // assert that the mocks are in the expected clean state
+    expect(mockAddUseElement).not.toHaveBeenCalled();
+    expect(mockAddElement).not.toHaveBeenCalled();
+
+    const result = renderInTestProvider(<App />);
+
+    // the hook should have been called in the render process but not the callback
+    expect(mockAddUseElement).toHaveBeenCalled();
+    expect(mockAddElement).not.toHaveBeenCalled();
+
+    // get a reference to the do something cool button element
+    const doSomethingCoolBtn = result.getByRole("button", {
+      name: "Do something cool",
+    });
+
+    // programmatically simulate clicking the button
+    fireEvent.click(doSomethingCoolBtn);
+
+    // we expect that addElement has been called by the button's click handler
+    expect(mockAddElement).toHaveBeenCalled();
+  });
+
+  // this test uses a mock in place of the @canva/platform requestOpenExternalUrl function
+  it("should call `requestOpenExternalUrl` when the button is clicked", () => {
+    expect(mockRequestOpenExternalUrl).not.toHaveBeenCalled();
+
+    const result = renderInTestProvider(<App />);
+
+    // get a reference to the Apps SDK button by name
+    const sdkButton = result.getByRole("button", {
+      name: "Open Canva Apps SDK docs",
+    });
+
+    expect(mockRequestOpenExternalUrl).not.toHaveBeenCalled();
+    fireEvent.click(sdkButton);
+    expect(mockRequestOpenExternalUrl).toHaveBeenCalled();
+
+    // assert that the requestOpenExternalUrl function was called with the expected arguments
+    expect(mockRequestOpenExternalUrl.mock.calls[0][0]).toEqual({
+      url: DOCS_URL,
+    });
+  });
+
+  // this test demonstrates the use of a snapshot test
+  it("should have a consistent snapshot", () => {
+    const result = renderInTestProvider(<App />);
+    expect(result.container).toMatchSnapshot();
+  });
+});

package/templates/hello_world/utils/use_add_element.ts

@@ -7,9 +7,9 @@ import type {
   VideoElement,
 } from "@canva/design";
 import { addElementAtCursor, addElementAtPoint } from "@canva/design";
-import { useFeatureSupport } from "./use_feature_support";
 import { features } from "@canva/platform";
 import { useEffect, useState } from "react";
+import { useFeatureSupport } from "./use_feature_support";
 
 type AddElementParams =
   | ImageElement

package/templates/hello_world/utils/use_feature_support.ts

@@ -1,6 +1,6 @@
 import { features } from "@canva/platform";
 import type { Feature } from "@canva/platform";
-import { useState, useEffect } from "react";
+import { useEffect, useState } from "react";
 
 /**
  * This hook allows re-rendering of a React component whenever