@canva/cli 0.0.1-beta.2 → 0.0.1-beta.20

package/templates/common/README.md

@@ -63,18 +63,15 @@ To preview apps in Safari:
 1. Start the development server with HTTPS enabled:
 
 ```bash
-# Run the main app
 npm start --use-https
-
-# Run an example
-npm start <example-name> --use-https
 ```
 
 2. Navigate to <https://localhost:8080>.
 3. Bypass the invalid security certificate warning:
-4. Click **Show details**.
-5. Click **Visit website**.
-6. In the Developer Portal, set the app's **Development URL** to <https://localhost:8080>.
+   1. Click **Show details**.
+   2. Click **Visit website**.
+4. In the Developer Portal, set the app's **Development URL** to <https://localhost:8080>.
+5. Click preview (or refresh your app if it's already open).
 
 You need to bypass the invalid security certificate warning every time you start the local server. A similar warning will appear in other browsers (and will need to be bypassed) whenever HTTPS is enabled.
 
@@ -181,70 +178,3 @@ To use ngrok, you'll need to do the following:
    ```
 
 This environment variable is available for the current terminal session, so the command must be re-run for each new session. Alternatively, you can add the variable to your terminal's default parameters.
-
-## Run the development server with ngrok and add authentication to the app
-
-These steps demonstrate how to start the local development server with ngrok.
-
-From your app's root directory
-
-1. Stop any running scripts, and run the following command to launch the backend and frontend development servers. The `--ngrok` parameter exposes the backend server via a publicly accessible URL.
-
-   ```bash
-   npm start --ngrok
-   ```
-
-2. After ngrok is running, copy your ngrok url
-   (e.g. `https://0000-0000.ngrok-free.app`) to the clipboard.
-
-   1. Go to your app in the [Developer Portal](https://www.canva.com/developers/apps).
-   2. Navigate to the "Add authentication" section of your app.
-   3. Check "This app requires authentication"
-   4. In the "Redirect URL" text box, enter your ngrok url followed by `/redirect-url` e.g.
-      `https://0000-0000.ngrok-free.app/redirect-url`
-   5. In the "Authentication base URL" text box, enter your ngrok url followed by `/` e.g.
-      `https://0000-0000.ngrok-free.app/`
-      Note: Your ngrok URL changes each time you restart ngrok. Keep these fields up to
-      date to ensure your example authentication step will run.
-
-3. Make sure the app is authenticating users by making the following changes:
-
-   1. Replace
-
-      `router.post("/resources/find", async (req, res) => {`
-
-      with
-
-      `router.post("/api/resources/find", async (req, res) => {`
-
-      in [./backend/routers/auth.ts](./backend/routers/auth.ts). Adding `/api/` to the route ensures
-      the JWT middleware authenticates requests.
-
-   2. Replace
-
-      ``const url = new URL(`${BACKEND_HOST}/resources/find`);``
-
-      with
-
-      ``const url = new URL(`${BACKEND_HOST}/api/resources/find`);``
-
-      in [./adapter.ts](./adapter.ts)
-
-   3. Comment out these lines in [./app.tsx](./app.tsx)
-
-      ```typescript
-      // Comment this next line out for production apps
-      setAuthState("authenticated");
-      ```
-
-4. Navigate to your app at `https://www.canva.com/developers/apps`, and click **Preview** to preview the app.
-   1. A new screen will appear asking if you want to authenticate.
-      Press **Connect** to start the authentication flow.
-   2. A ngrok screen may appear. If it does, select **Visit Site**
-   3. An authentication popup will appear. For the username, enter `username`, and
-      for the password enter `password`.
-   4. If successful, you will be redirected back to your app.
-5. You can now modify the `/redirect-url` function in `server.ts` to authenticate with your third-party
-   asset manager, and `/api/resources/find` to pull assets from your third-party asset manager.
-
-   See `https://www.canva.dev/docs/apps/authenticating-users/` for more details.

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/conf/{eslint-general.mjs → eslint_general.mjs}

@@ -2,6 +2,7 @@ import typescriptEslint from "@typescript-eslint/eslint-plugin";
 import jest from "eslint-plugin-jest";
 import react from "eslint-plugin-react";
 import globals from "globals";
+import eslintPluginUnicorn from "eslint-plugin-unicorn";
 
 export default [
   {
@@ -9,6 +10,7 @@ export default [
       "@typescript-eslint": typescriptEslint,
       jest,
       react,
+      unicorn: eslintPluginUnicorn,
     },
     languageOptions: {
       globals: {
@@ -178,6 +180,38 @@ export default [
           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/",
         },
+        {
+          selector:
+            "MemberExpression[object.name='localStorage'], MemberExpression[object.name='sessionStorage']",
+          message:
+            "Using `localStorage` or `sessionStorage` may not be appropriate for certain types of data, such as sensitive information. If your use case is safe and does not involve storing sensitive data (e.g., access tokens or keys), you can ignore this warning with an eslint-disable comment. Otherwise, seek secure storage alternatives. For more details, refer to the Canva Security Guidelines (https://www.canva.dev/docs/apps/security-guidelines/#store-secrets-securely).",
+        },
+      ],
+      "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",
@@ -194,6 +228,12 @@ export default [
       "prefer-rest-params": "error",
       "prefer-spread": "error",
       radix: "error",
+      "unicorn/filename-case": [
+        "error",
+        {
+          case: "snakeCase",
+        },
+      ],
     },
   },
   {

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/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,20 @@
+// 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");
+// n.b. @canva/error should not be mocked - use it to simulate API error responses from other mocks by throwing CanvaError

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");
+        });
+      });
+    },
+  };
+}