@canva/cli 0.0.1-beta.1 → 0.0.1-beta.10

package/templates/common/conf/eslint-general.mjs

@@ -0,0 +1,303 @@
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import jest from "eslint-plugin-jest";
+import react from "eslint-plugin-react";
+import globals from "globals";
+
+export default [
+  {
+    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-restricted-imports": [
+        "warn",
+        {
+          // Warn when importing static assets that increase bundle size
+          patterns: [
+            // Images
+            {
+              group: ["*.png", "*.jpg", "*.jpeg", "*.gif"],
+              message:
+                "Inline images increase app bundle size and degrade app performance. Wherever possible, please use a CDN or external hosting service to dynamically load assets.",
+            },
+            // Videos
+            {
+              group: ["*.mp4", "*.webm", "*.ogg"],
+              message:
+                "Inline videos increase app bundle size and degrade app performance. Wherever possible, please use a CDN or external hosting service to dynamically load assets.",
+            },
+            // Audio
+            {
+              group: ["*.mp3", "*.wav", "*.ogg"],
+              message:
+                "Inline audio files increase app bundle size and degrade app performance. Wherever possible, please use a CDN or external hosting service to dynamically load assets.",
+            },
+          ],
+        },
+      ],
+      "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/common/conf/eslint-i18n.mjs

@@ -0,0 +1,41 @@
+import formatjs from "eslint-plugin-formatjs";
+import eslintLocalI18nRules from "./eslint-local-i18n-rules/index.mjs";
+
+export default [
+  {
+    plugins: {
+      formatjs,
+      "local-i18n-rules": eslintLocalI18nRules,
+    },
+    rules: {
+      "formatjs/no-invalid-icu": "error",
+      "formatjs/no-literal-string-in-jsx": [
+        2,
+        {
+          props: {
+            // These rules are for @canva/app-ui-kit components.
+            // For your own components, suppress any false positives using eslint ignore comments.
+            include: [
+              ["*", "(*Label|label|alt)"],
+              ["*", "(title|description|name|text)"],
+              ["*", "(placeholder|additionalPlaceholder|defaultValue)"],
+              ["FormField", "error"],
+            ],
+            exclude: [["FormattedMessage", "description"]],
+          },
+        },
+      ],
+      "formatjs/enforce-description": ["error", "literal"],
+      "formatjs/enforce-default-message": ["error", "literal"],
+      "formatjs/enforce-placeholders": "error",
+      "formatjs/no-id": "error",
+      "formatjs/no-emoji": "error",
+      "formatjs/no-useless-message": "error",
+      "formatjs/no-multiple-plurals": "error",
+      "formatjs/no-offset": "error",
+      "formatjs/blocklist-elements": [2, ["selectordinal"]],
+      "formatjs/no-complex-selectors": "error",
+      "local-i18n-rules/enforce-object-property-translation": ["warn"],
+    },
+  },
+];

package/templates/common/conf/eslint-local-i18n-rules/index.mjs

@@ -0,0 +1,181 @@
+/**
+ * ESLint rule that identifies and flags untranslated user-facing strings in object properties.
+ *
+ * This rule helps maintain internationalization consistency by detecting untranslated
+ * strings in specific object properties (default: 'label'). It suggests using
+ * intl.formatMessage for proper translation.
+ *
+ * Note: The rule is currently implemented as a local rule, with plans to publish as
+ * an npm package to make it available to the broader development community.
+ *
+ * @example
+ * // ❌ Incorrect - Untranslated strings
+ * const options = [
+ *   { value: "inbox", label: "Inbox" },
+ *   { value: "starred", label: "Starred messages" },
+ *   { value: "spam", label: "Spam folder" }
+ * ];
+ *
+ * // ✅ Correct - Using intl.formatMessage with descriptions
+ * const options = [
+ *   {
+ *     value: "inbox",
+ *     label: intl.formatMessage({
+ *       defaultMessage: "Inbox",
+ *       description: "Label for main message inbox folder option"
+ *     })
+ *   },
+ *   {
+ *     value: "starred",
+ *     label: intl.formatMessage({
+ *       defaultMessage: "Starred messages",
+ *       description: "Label for folder containing messages marked as important"
+ *     })
+ *   },
+ *   {
+ *     value: "spam",
+ *     label: intl.formatMessage({
+ *       defaultMessage: "Spam folder",
+ *       description: "Label for folder containing filtered spam messages"
+ *     })
+ *   }
+ * ];
+ *
+ * @see https://www.canva.dev/docs/apps/localization/
+ */
+export default {
+  rules: {
+    "enforce-object-property-translation": {
+      meta: {
+        type: "problem",
+        docs: {
+          description:
+            "Enforce translation of specific properties using intl.formatMessage",
+          category: "Possible Errors",
+          recommended: true,
+        },
+        fixable: "code",
+        schema: [
+          {
+            type: "object",
+            properties: {
+              properties: {
+                type: "array",
+                items: { type: "string" },
+                default: ["label"],
+              },
+              intlObjectName: {
+                type: "string",
+                default: "intl",
+              },
+            },
+            additionalProperties: false,
+          },
+        ],
+        messages: {
+          untranslatedProperty: `If "{{ originalMessage }}" is a user-facing string, you should translate it using "intl.formatMessage". See https://www.canva.dev/docs/apps/localization/.`,
+        },
+      },
+      create(context) {
+        const config = context.options[0] || {};
+        const propertiesToCheck = config.properties || ["label"];
+        const intlObjectName = config.intlObjectName || "intl";
+
+        function getTemplateLiteralString(node) {
+          const src = context.getSourceCode();
+          return src.getText(node);
+        }
+
+        // Extract string content from different node types
+        function extractStringContent(node) {
+          if (!node) return [];
+
+          switch (node.type) {
+            // label: "Foo"
+            case "Literal":
+              return typeof node.value === "string"
+                ? [{ node, value: node.value }]
+                : [];
+
+            // label: `Foo ${bar}`
+            case "TemplateLiteral":
+              return [{ node, value: getTemplateLiteralString(node) }];
+            // label: foo || "Bar"
+            case "LogicalExpression": {
+              if (node.operator === "||") {
+                return [
+                  ...extractStringContent(node.left),
+                  ...extractStringContent(node.right),
+                ];
+              }
+              return [];
+            }
+            // label: "Foo" + "Bar" + "Baz"
+            case "BinaryExpression":
+              if (node.operator === "+") {
+                return [
+                  ...extractStringContent(node.left),
+                  ...extractStringContent(node.right),
+                ];
+              }
+              return [];
+            // label: foo ? "Foo" : "Bar"
+            case "ConditionalExpression":
+              return [
+                ...extractStringContent(node.consequent),
+                ...extractStringContent(node.alternate),
+              ];
+
+            default:
+              return [];
+          }
+        }
+
+        function isTranslated(node) {
+          return (
+            node.parent.type === "CallExpression" &&
+            node.parent.callee.type === "MemberExpression" &&
+            node.parent.callee.object.name === intlObjectName &&
+            node.parent.callee.property.name === "formatMessage"
+          );
+        }
+
+        return {
+          Property(node) {
+            const keyName = node.key.name || node.key.value;
+            if (propertiesToCheck.includes(keyName)) {
+              const results = extractStringContent(node.value);
+              if (!results) return;
+              results.forEach((result) => {
+                const { node: stringNode, value: stringValue } = result;
+
+                if (!isTranslated(stringNode)) {
+                  context.report({
+                    node: stringNode,
+                    messageId: "untranslatedProperty",
+                    data: {
+                      property: keyName,
+                      originalMessage:
+                        stringValue.length > 40
+                          ? stringValue.split(" ").slice(0, 4).join(" ") + "..."
+                          : stringValue,
+                      intlObjectName,
+                    },
+                    fix(fixer) {
+                      const newText = `${intlObjectName}.formatMessage({
+            defaultMessage: ${JSON.stringify(stringValue)},
+            // TODO: Provide a meaningful description for translators
+            description: ""
+          })`;
+                      return fixer.replaceText(stringNode, newText);
+                    },
+                  });
+                }
+              });
+            }
+          },
+        };
+      },
+    },
+  },
+};

package/templates/common/jest.config.mjs

@@ -1,8 +1,35 @@
+import { pathsToModuleNameMapper } from "ts-jest";
+import tsconfig from "./tsconfig.json" assert { type: "json" };
+
+const { compilerOptions } = tsconfig;
+
 /** @type {import('ts-jest').JestConfigWithTsJest} */
 
 export default {
   preset: "ts-jest",
-  testEnvironment: "node",
-  testRegex: "(/tests/.*|(\\.|/)(tests))\\.ts?$",
+  testEnvironment: "jsdom",
+  testRegex: "(/tests/.*|(\\.|/)(tests))\\.tsx?$",
   modulePathIgnorePatterns: ["./internal/", "./node_modules/"],
+  modulePaths: [compilerOptions.baseUrl],
+  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths),
+  transform: {
+    ".+\\.(css)$": "jest-css-modules-transform",
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        astTransformers: {
+          before: [
+            {
+              path: "@formatjs/ts-transformer/ts-jest-integration",
+              options: {
+                overrideIdFn: "[sha512:contenthash:base64:6]",
+                ast: true,
+              },
+            },
+          ],
+        },
+      },
+    ],
+  },
+  setupFiles: ["<rootDir>/jest.setup.ts"],
 };

package/templates/common/jest.setup.ts

@@ -0,0 +1,19 @@
+// Import testing sub-packages
+import * as asset from "@canva/asset/test";
+import * as design from "@canva/design/test";
+import * as error from "@canva/error/test";
+import * as platform from "@canva/platform/test";
+import * as user from "@canva/user/test";
+
+// Initialize the test environments
+asset.initTestEnvironment();
+design.initTestEnvironment();
+error.initTestEnvironment();
+platform.initTestEnvironment();
+user.initTestEnvironment();
+
+// Once they're initialized, mock the SDKs
+jest.mock("@canva/asset");
+jest.mock("@canva/design");
+jest.mock("@canva/platform");
+jest.mock("@canva/user");

package/templates/common/utils/backend/base_backend/create.ts

@@ -0,0 +1,104 @@
+/* eslint-disable no-console */
+import * as express from "express";
+import * as http from "http";
+import * as https from "https";
+import * as fs from "fs";
+import type { Request, Response, NextFunction } from "express";
+import debug from "debug";
+
+const serverDebug = debug("server");
+
+interface BaseServer {
+  app: express.Express;
+
+  /**
+   * Starts the server on the address or port provided
+   * @param address port number or string address or if left undefined express defaults to port 3000
+   */
+  start: (address: number | string | undefined) => void;
+}
+
+/**
+ * createBaseServer instantiates a customised express server with:
+ * - json body handling
+ * - health check endpoint
+ * - catchall endpoint
+ * - error handler catch route
+ * - process termination handling
+ * - debug logging - prefix starting your server with `DEBUG=server npm run XXX`
+ *
+ * @returns BaseServer object containing the express app and a start function
+ */
+export function createBaseServer(router: express.Router): BaseServer {
+  const SHOULD_ENABLE_HTTPS = process.env?.SHOULD_ENABLE_HTTPS === "true";
+  const HTTPS_CERT_FILE = process.env?.HTTPS_CERT_FILE;
+  const HTTPS_KEY_FILE = process.env?.HTTPS_KEY_FILE;
+
+  const app = express();
+  app.use(express.json());
+
+  // It can help to provide an extra layer of obsecurity to reduce server fingerprinting.
+  app.disable("x-powered-by");
+
+  // Health check endpoint
+  app.get("/healthz", (req, res: Response) => {
+    res.sendStatus(200);
+  });
+
+  // logging middleware
+  app.use((req: Request, res: Response, next: NextFunction) => {
+    serverDebug(`${new Date().toISOString()}: ${req.method} ${req.url}`);
+    next();
+  });
+
+  // Custom routes router
+  app.use(router);
+
+  // catch all router
+  app.all("*", (req, res) => {
+    res.status(404).send({
+      error: `unhandled '${req.method}' on '${req.url}'`,
+    });
+  });
+
+  // default error handler
+  app.use((err, req, res, next) => {
+    console.error(err.stack);
+    res.status(500).send({
+      error: "something went wrong",
+    });
+  });
+
+  let server;
+  if (SHOULD_ENABLE_HTTPS) {
+    if (!HTTPS_CERT_FILE || !HTTPS_KEY_FILE) {
+      throw new Error(
+        "Looks like you're running the example with --use-https flag, but SSL certificates haven't been generated. Please remove the .ssl/ folder and re-run the command again.",
+      );
+    }
+
+    server = https.createServer(
+      {
+        key: fs.readFileSync(HTTPS_KEY_FILE),
+        cert: fs.readFileSync(HTTPS_CERT_FILE),
+      },
+      app,
+    );
+  } else {
+    server = http.createServer(app);
+  }
+
+  return {
+    app,
+    start: (address: number | string | undefined) => {
+      console.log(`Listening on '${address}'`);
+      server.listen(address);
+      process.on("SIGTERM", () => {
+        serverDebug("SIGTERM signal received: closing HTTP server");
+        server.close(() => {
+          serverDebug("HTTP server closed");
+        });
+      });
+    },
+  };
+}