@canva/cli 1.19.0 → 1.20.0

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

@@ -1,223 +0,0 @@
-/* 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);
-    }
-  };
-}

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

@@ -1,171 +0,0 @@
-import fs from "fs";
-import path from "path";
-
-interface CliArgs {
-  example?: string;
-  useHttps: boolean;
-  ngrok: boolean;
-  preview: boolean;
-  overrideFrontendPort?: number;
-}
-
-interface EnvVars {
-  frontendPort: number;
-  backendPort: number;
-  hmrEnabled: boolean;
-  appId?: string;
-  appOrigin?: string;
-  backendHost?: string;
-}
-
-export class Context {
-  private readonly envVars: EnvVars;
-
-  constructor(
-    private env: NodeJS.ProcessEnv = process.env,
-    private readonly args: CliArgs,
-  ) {
-    this.envVars = this.parseAndValidateEnvironmentVariables();
-  }
-
-  static get srcDir() {
-    const src = path.join(Context.rootDir, "src");
-
-    if (!fs.existsSync(src)) {
-      throw new Error(`Directory does not exist: ${src}`);
-    }
-
-    return src;
-  }
-
-  static get readmeDir() {
-    return path.join(Context.rootDir, "README.md");
-  }
-
-  get entryDir() {
-    return Context.srcDir;
-  }
-
-  get ngrokEnabled() {
-    return this.args.ngrok;
-  }
-
-  get hmrEnabled() {
-    return this.envVars.hmrEnabled;
-  }
-
-  get httpsEnabled() {
-    return this.args.useHttps;
-  }
-
-  get frontendEntryPath() {
-    const frontendEntryPath = path.join(this.entryDir, "index.tsx");
-
-    if (!fs.existsSync(frontendEntryPath)) {
-      throw new Error(
-        `Entry point for frontend does not exist: ${frontendEntryPath}`,
-      );
-    }
-
-    return frontendEntryPath;
-  }
-
-  get frontendUrl() {
-    return `${this.protocol}://localhost:${this.frontendPort}`;
-  }
-
-  get frontendPort() {
-    return this.args.overrideFrontendPort || this.envVars.frontendPort;
-  }
-
-  get developerBackendEntryPath(): string | undefined {
-    const developerBackendEntryPath = path.join(
-      Context.rootDir,
-      "backend",
-      "server.ts",
-    );
-
-    if (!fs.existsSync(developerBackendEntryPath)) {
-      return undefined;
-    }
-
-    return developerBackendEntryPath;
-  }
-
-  get backendUrl() {
-    return `${this.protocol}://localhost:${this.envVars.backendPort}`;
-  }
-
-  get backendHost() {
-    let backendHost = this.envVars.backendHost;
-
-    // if there's no custom URL provided by the developer, we fallback to our localhost backend
-    if (!backendHost || backendHost.trim() === "") {
-      backendHost = this.backendUrl;
-    }
-
-    return backendHost;
-  }
-
-  get backendPort() {
-    return this.envVars.backendPort;
-  }
-
-  get appOrigin(): string | undefined {
-    return this.envVars.appOrigin;
-  }
-
-  get appId(): string | undefined {
-    return this.envVars.appId;
-  }
-
-  get openPreview(): boolean {
-    return this.args.preview;
-  }
-
-  private get protocol(): "https" | "http" {
-    return this.httpsEnabled ? "https" : "http";
-  }
-
-  private static get rootDir() {
-    return path.join(process.cwd());
-  }
-
-  private parseAndValidateEnvironmentVariables(): EnvVars {
-    const {
-      CANVA_FRONTEND_PORT,
-      CANVA_BACKEND_PORT,
-      CANVA_BACKEND_HOST,
-      CANVA_APP_ID,
-      CANVA_APP_ORIGIN,
-      CANVA_HMR_ENABLED,
-    } = this.env;
-
-    if (!CANVA_FRONTEND_PORT) {
-      throw new Error(
-        "CANVA_FRONTEND_PORT environment variable is not defined",
-      );
-    }
-
-    if (!CANVA_BACKEND_PORT) {
-      throw new Error("CANVA_BACKEND_PORT environment variable is not defined");
-    }
-
-    const envVars: EnvVars = {
-      frontendPort: parseInt(CANVA_FRONTEND_PORT, 10),
-      backendPort: parseInt(CANVA_BACKEND_PORT, 10),
-      hmrEnabled: CANVA_HMR_ENABLED?.toLowerCase().trim() === "true",
-      appId: CANVA_APP_ID,
-      appOrigin: CANVA_APP_ORIGIN,
-      backendHost: CANVA_BACKEND_HOST,
-    };
-
-    if (envVars.hmrEnabled && envVars.appOrigin == null) {
-      throw new Error(
-        "CANVA_HMR_ENABLED environment variable is TRUE, but CANVA_APP_ORIGIN is not set. Refer to the instructions in the README.md on configuring HMR.",
-      );
-    }
-
-    return envVars;
-  }
-}

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

@@ -1,46 +0,0 @@
-#!/usr/bin/env node
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
-import { AppRunner } from "./app_runner";
-import { Context } from "./context";
-
-const appRunner = new AppRunner();
-
-yargs(hideBin(process.argv))
-  .version(false)
-  .help()
-  .option("ngrok", {
-    description: "Run backend server via ngrok.",
-    type: "boolean",
-    // npm swallows command line args instead of forwarding to the script
-    default:
-      process.env.npm_config_ngrok?.toLocaleLowerCase().trim() === "true",
-  })
-  .option("use-https", {
-    description: "Start local development server on HTTPS.",
-    type: "boolean",
-    // npm swallows commands line args instead of forwarding to the script
-    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",
-    () => {},
-    (args) => {
-      const ctx = new Context(process.env, args);
-      appRunner.run(ctx);
-    },
-  )
-  .parse();

package/templates/hello_world/src/index.tsx

@@ -1,4 +0,0 @@
-import { prepareDesignEditor } from "@canva/intents/design";
-import designEditor from "./intents/design_editor";
-
-prepareDesignEditor(designEditor);

package/templates/hello_world/src/intents/design_editor/app.tsx

@@ -1,86 +0,0 @@
-import { useFeatureSupport } from "@canva/app-hooks";
-import { Button, Rows, Text } from "@canva/app-ui-kit";
-import { addElementAtCursor, addElementAtPoint } from "@canva/design";
-import { requestOpenExternalUrl } from "@canva/platform";
-import { FormattedMessage, useIntl } from "react-intl";
-import * as styles from "styles/components.css";
-
-export const DOCS_URL = "https://www.canva.dev/docs/apps/";
-
-export const App = () => {
-  const isSupported = useFeatureSupport();
-  const addElement = [addElementAtPoint, addElementAtCursor].find((fn) =>
-    isSupported(fn),
-  );
-
-  const onClick = () => {
-    if (!addElement) {
-      return;
-    }
-
-    addElement({
-      type: "text",
-      children: ["Hello world!"],
-    });
-  };
-
-  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 (
-    <div className={styles.scrollContainer}>
-      <Rows spacing="2u">
-        <Text>
-          <FormattedMessage
-            defaultMessage="
-              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.
-            "
-            description="Instructions for how to make changes to the app. Do not translate <code>src/app.tsx</code>."
-            values={{
-              code: (chunks) => <code>{chunks}</code>,
-            }}
-          />
-        </Text>
-        <Button
-          variant="primary"
-          onClick={onClick}
-          disabled={!addElement}
-          tooltipLabel={
-            !addElement
-              ? intl.formatMessage({
-                  defaultMessage:
-                    "This feature is not supported in the current page",
-                  description:
-                    "Tooltip label for when a feature is not supported in the current design",
-                })
-              : undefined
-          }
-          stretch
-        >
-          {intl.formatMessage({
-            defaultMessage: "Do something cool",
-            description:
-              "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/intents/design_editor/index.tsx

@@ -1,25 +0,0 @@
-import "@canva/app-ui-kit/styles.css";
-import { AppI18nProvider } from "@canva/app-i18n-kit";
-import { AppUiProvider } from "@canva/app-ui-kit";
-import type { DesignEditorIntent } from "@canva/intents/design";
-import { createRoot } from "react-dom/client";
-import { App } from "./app";
-
-async function render() {
-  const root = createRoot(document.getElementById("root") as Element);
-
-  root.render(
-    <AppI18nProvider>
-      <AppUiProvider>
-        <App />
-      </AppUiProvider>
-    </AppI18nProvider>,
-  );
-}
-
-const designEditor: DesignEditorIntent = { render };
-export default designEditor;
-
-if (module.hot) {
-  module.hot.accept("./app", render);
-}

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

@@ -1,45 +0,0 @@
-// 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/intents/design_editor/tests/app.tests.tsx

@@ -1,92 +0,0 @@
-/* eslint-disable formatjs/no-literal-string-in-jsx */
-import { useFeatureSupport } from "@canva/app-hooks";
-import { TestAppI18nProvider } from "@canva/app-i18n-kit";
-import { TestAppUiProvider } from "@canva/app-ui-kit";
-import { addElementAtCursor, addElementAtPoint } from "@canva/design";
-import type { Feature } from "@canva/platform";
-import { requestOpenExternalUrl } from "@canva/platform";
-import { fireEvent, render } from "@testing-library/react";
-import type { RenderResult } from "@testing-library/react";
-import type { ReactNode } from "react";
-import { App, DOCS_URL } from "../app";
-
-function renderInTestProvider(node: 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("@canva/app-hooks");
-
-// 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", () => {
-  const mockIsSupported = jest.fn();
-  const mockUseFeatureSupport = jest.mocked(useFeatureSupport);
-  const mockRequestOpenExternalUrl = jest.mocked(requestOpenExternalUrl);
-
-  beforeEach(() => {
-    jest.resetAllMocks();
-    mockIsSupported.mockImplementation(
-      (fn: Feature) => fn === addElementAtPoint,
-    );
-    mockUseFeatureSupport.mockReturnValue(mockIsSupported);
-    mockRequestOpenExternalUrl.mockResolvedValue({ status: "completed" });
-  });
-
-  // this test uses a mock in place of the useFeatureSupport hook
-  it("should add a text element when the button is clicked", () => {
-    // assert that the mocks are in the expected clean state
-    expect(mockUseFeatureSupport).not.toHaveBeenCalled();
-    expect(addElementAtPoint).not.toHaveBeenCalled();
-
-    const result = renderInTestProvider(<App />);
-
-    // the hook should have been called in the render process but not the callback
-    expect(mockUseFeatureSupport).toHaveBeenCalled();
-    expect(addElementAtPoint).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 addElementAtPoint has been called by the button's click handler
-    expect(mockIsSupported).toHaveBeenCalledWith(addElementAtPoint);
-    expect(mockIsSupported).not.toHaveBeenCalledWith(addElementAtCursor);
-    expect(addElementAtPoint).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();
-  });
-});