@canva/cli 0.0.1-beta.1

package/templates/dam/eslint.config.mjs

@@ -0,0 +1,309 @@
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import jest from "eslint-plugin-jest";
+import react from "eslint-plugin-react";
+import globals from "globals";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+export default [
+  {
+    ignores: [
+      "**/node_modules/",
+      "**/dist",
+      "**/*.d.ts",
+      "**/*.d.tsx",
+      "**/sdk",
+      "**/internal",
+      "**/*.config.*",
+    ],
+  },
+  ...compat.extends(
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/strict",
+    "plugin:@typescript-eslint/stylistic",
+    "plugin:react/recommended",
+    "plugin:jest/recommended"
+  ),
+  {
+    plugins: {
+      "@typescript-eslint": typescriptEslint,
+      jest,
+      react,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.serviceworker,
+        ...globals.browser,
+      },
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-non-null-assertion": "warn",
+      "@typescript-eslint/no-empty-function": "off",
+      "@typescript-eslint/consistent-type-imports": "error",
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-empty-interface": "warn",
+      "@typescript-eslint/consistent-type-definitions": "off",
+      "@typescript-eslint/explicit-member-accessibility": [
+        "error",
+        {
+          accessibility: "no-public",
+          overrides: {
+            parameterProperties: "off",
+          },
+        },
+      ],
+      "@typescript-eslint/naming-convention": [
+        "error",
+        {
+          selector: "typeLike",
+          format: ["PascalCase"],
+          leadingUnderscore: "allow",
+        },
+      ],
+      "no-invalid-this": "off",
+      "@typescript-eslint/no-invalid-this": "error",
+      "@typescript-eslint/no-unused-expressions": [
+        "error",
+        {
+          allowShortCircuit: true,
+          allowTernary: true,
+        },
+      ],
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          vars: "all",
+          varsIgnorePattern: "^_",
+          args: "none",
+          ignoreRestSiblings: true,
+        },
+      ],
+      "@typescript-eslint/no-require-imports": "error",
+      "jest/no-restricted-matchers": [
+        "error",
+        {
+          toContainElement:
+            "toContainElement is not recommended as it encourages testing the internals of the components",
+          toContainHTML:
+            "toContainHTML is not recommended as it encourages testing the internals of the components",
+          toHaveAttribute:
+            "toHaveAttribute is not recommended as it encourages testing the internals of the components",
+          toHaveClass:
+            "toHaveClass is not recommended as it encourages testing the internals of the components",
+          toHaveStyle:
+            "toHaveStyle is not recommended as it encourages testing the internals of the components",
+        },
+      ],
+      "react/jsx-curly-brace-presence": [
+        "error",
+        {
+          props: "never",
+          children: "never",
+        },
+      ],
+      "react/jsx-tag-spacing": [
+        "error",
+        {
+          closingSlash: "never",
+          beforeSelfClosing: "allow",
+          afterOpening: "never",
+          beforeClosing: "allow",
+        },
+      ],
+      "react/self-closing-comp": "error",
+      "react/no-unescaped-entities": "off",
+      "react/jsx-uses-react": "off",
+      "react/react-in-jsx-scope": "off",
+      "default-case": "error",
+      eqeqeq: [
+        "error",
+        "always",
+        {
+          null: "never",
+        },
+      ],
+      "no-caller": "error",
+      "no-console": "error",
+      "no-eval": "error",
+      "no-inner-declarations": "error",
+      "no-new-wrappers": "error",
+      "no-restricted-globals": [
+        "error",
+        {
+          name: "fit",
+          message: "Don't focus tests",
+        },
+        {
+          name: "fdescribe",
+          message: "Don't focus tests",
+        },
+        {
+          name: "length",
+          message:
+            "Undefined length - Did you mean to use window.length instead?",
+        },
+        {
+          name: "name",
+          message: "Undefined name - Did you mean to use window.name instead?",
+        },
+        {
+          name: "status",
+          message:
+            "Undefined status - Did you mean to use window.status instead?",
+        },
+        {
+          name: "spyOn",
+          message: "Don't use spyOn directly, use jest.spyOn",
+        },
+      ],
+      "no-restricted-properties": [
+        "error",
+        {
+          property: "bind",
+          message: "Don't o.f.bind(o, ...), use () => o.f(...)",
+        },
+        {
+          object: "ReactDOM",
+          property: "findDOMNode",
+          message: "Don't use ReactDOM.findDOMNode() as it is deprecated",
+        },
+      ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "AccessorProperty, TSAbstractAccessorProperty",
+          message:
+            "Accessor property syntax is not allowed, use getter and setters.",
+        },
+        {
+          selector: "PrivateIdentifier",
+          message:
+            "Private identifiers are not allowed, use TypeScript private fields.",
+        },
+        {
+          selector:
+            "JSXOpeningElement[name.name = /^[A-Z]/] > JSXAttribute[name.name = /-/]",
+          message:
+            "Passing hyphenated props to custom components is not type-safe. Prefer a camelCased equivalent if available. (See https://github.com/microsoft/TypeScript/issues/55182)",
+        },
+        {
+          selector:
+            "CallExpression[callee.object.name='window'][callee.property.name='open']",
+          message:
+            "Apps are currently not allowed to open popups, or new tabs via browser APIs. Please use `requestOpenExternalUrl` from `@canva/platform` to link to external URLs. To learn more, see https://www.canva.dev/docs/apps/api/platform-request-open-external-url/",
+        },
+      ],
+      "no-return-await": "error",
+      "no-throw-literal": "error",
+      "no-undef-init": "error",
+      "no-var": "error",
+      "object-shorthand": "error",
+      "prefer-const": [
+        "error",
+        {
+          destructuring: "all",
+        },
+      ],
+      "prefer-object-spread": "error",
+      "prefer-rest-params": "error",
+      "prefer-spread": "error",
+      radix: "error",
+    },
+  },
+  {
+    files: ["**/*.tsx"],
+    rules: {
+      "react/no-deprecated": "error",
+      "react/forbid-elements": [
+        "error",
+        {
+          forbid: [
+            {
+              element: "video",
+              message:
+                "Don't use HTML video directly. Instead, use the App UI Kit <VideoCard /> as this respects users' auto-playing preferences",
+            },
+            {
+              element: "em",
+              message:
+                "Don't use <em> to italicize text. Canva's UI fonts don't support italic font style.",
+            },
+            {
+              element: "i",
+              message:
+                "Don't use <i> to italicize text. Canva's UI fonts don't support italic font style.",
+            },
+            {
+              element: "iframe",
+              message:
+                "Canva Apps aren't allowed to contain iframes. You should either recreate the UI you want to show in the iframe in the app directly, or link to your page via a `<Link>` tag.  For more info see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+            {
+              element: "script",
+              message:
+                "Script tags are not allowed in Canva SDK Apps. You should import JavaScript modules instead. For more info see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+            {
+              element: "a",
+              message:
+                "Don't use <a> tags. Instead, use the <Link> component from the App UI Kit, and remember to open the url via the requestOpenExternalUrl method from @canva/platform.",
+            },
+            {
+              element: "img",
+              message:
+                "Have you considered using <ImageCard /> from the App UI Kit instead?",
+            },
+            {
+              element: "embed",
+              message:
+                "Have you considered using <EmbedCard /> from the App UI Kit instead?",
+            },
+            {
+              element: "audio",
+              message:
+                "Have you considered using <AudioCard /> from the App UI Kit instead?",
+            },
+            {
+              element: "button",
+              message:
+                "Rather than using the native HTML <button> element, use the <Button> component from the App UI Kit for consistency and accessibility.",
+            },
+            {
+              element: "input",
+              message:
+                "Wherever possible, prefer using the form inputs from the App UI Kit for consistency and accessibility (TextInput, Checkbox, FileInput, etc).",
+            },
+            {
+              element: "base",
+              message:
+                "The <base> tag is not supported in Canva Apps. We recommend using hash-based routing. For more on what is and isn't allowed in Canva Apps see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+            {
+              element: "link",
+              message:
+                "If you're trying to include a css stylesheet, we recommend importing css using React, or using embedded stylesheets. For more on what is and isn't allowed in Canva Apps see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];

package/templates/dam/package.json

@@ -0,0 +1,90 @@
+{
+  "private": true,
+  "name": "digital_asset_management",
+  "description": "An example app leveraging @canva/app-components to develop a digital asset management (DAM) 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",
+    "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",
+    "test": "jest --no-cache",
+    "test:watch": "jest --watchAll"
+  },
+  "dependencies": {
+    "@canva/app-i18n-kit": "^0.0.1-beta.5",
+    "@canva/app-components": "^1.0.0-beta.22",
+    "@canva/app-ui-kit": "^3.8.0",
+    "@canva/asset": "^1.7.1",
+    "@canva/design": "^1.10.0",
+    "@canva/platform": "^1.1.0",
+    "@canva/user": "^1.0.0",
+    "cookie-parser": "1.4.6",
+    "cors": "2.8.5",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-intl": "6.6.8"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "3.1.0",
+    "@eslint/js": "9.9.0",
+    "@formatjs/cli": "6.2.12",
+    "@formatjs/ts-transformer": "3.13.14",
+    "@ngrok/ngrok": "1.4.1",
+    "@svgr/webpack": "8.1.0",
+    "@types/cors": "2.8.17",
+    "@types/debug": "4.1.12",
+    "@types/express": "4.17.21",
+    "@types/express-serve-static-core": "4.19.5",
+    "@types/jest": "29.5.12",
+    "@types/jsonwebtoken": "9.0.6",
+    "@types/node": "20.10.0",
+    "@types/node-fetch": "2.6.11",
+    "@types/node-forge": "1.3.11",
+    "@types/nodemon": "1.19.6",
+    "@types/prompts": "2.4.9",
+    "@types/react": "18.3.4",
+    "@types/react-dom": "18.3.0",
+    "@types/webpack-env": "1.18.5",
+    "@typescript-eslint/eslint-plugin": "8.2.0",
+    "@typescript-eslint/parser": "8.2.0",
+    "chalk": "4.1.2",
+    "cli-table3": "0.6.5",
+    "css-loader": "7.1.2",
+    "css-modules-typescript-loader": "4.0.1",
+    "cssnano": "7.0.5",
+    "debug": "4.3.6",
+    "dotenv": "16.4.5",
+    "eslint": "9.9.0",
+    "eslint-plugin-jest": "28.8.0",
+    "eslint-plugin-react": "7.35.0",
+    "exponential-backoff": "3.1.1",
+    "express": "4.19.2",
+    "express-basic-auth": "1.2.1",
+    "jest": "29.7.0",
+    "jsonwebtoken": "9.0.2",
+    "jwks-rsa": "3.1.0",
+    "mini-css-extract-plugin": "2.9.1",
+    "node-fetch": "3.3.2",
+    "node-forge": "1.3.1",
+    "nodemon": "3.0.1",
+    "postcss-loader": "8.1.1",
+    "prettier": "3.3.3",
+    "prompts": "2.4.2",
+    "style-loader": "4.0.0",
+    "terser-webpack-plugin": "5.3.10",
+    "ts-jest": "29.2.4",
+    "ts-loader": "9.5.1",
+    "ts-node": "10.9.2",
+    "typescript": "5.5.4",
+    "url-loader": "4.1.1",
+    "webpack": "5.94.0",
+    "webpack-cli": "5.1.4",
+    "webpack-dev-server": "5.0.4",
+    "yargs": "17.7.2"
+  }
+}

package/templates/dam/scripts/ssl/ssl.ts

@@ -0,0 +1,131 @@
+import * as crypto from "crypto";
+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");
+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/dam/scripts/start/app_runner.ts

@@ -0,0 +1,164 @@
+/* eslint-disable no-console */
+import type { Context } from "./context";
+import * as chalk from "chalk";
+import { buildConfig } from "../../webpack.config.cjs";
+import * as ngrok from "@ngrok/ngrok";
+import * as nodemon from "nodemon";
+import * as Table from "cli-table3";
+import * as webpack from "webpack";
+import * as WebpackDevServer from "webpack-dev-server";
+import type { Certificate } from "../ssl/ssl";
+import { createOrRetrieveCertificate } from "../ssl/ssl";
+
+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;
+
+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();
+
+    const server = await this.runWebpackDevServer(ctx, table, cert);
+
+    await this.maybeRunBackendServer(ctx, table, cert, server);
+
+    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;
+  };
+}