@canva/cli 0.0.1-beta.3 → 0.0.1-beta.31

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

@@ -1,12 +1,14 @@
 /* eslint-disable no-console */
 import type { Context } from "./context";
 import * as chalk from "chalk";
-import { buildConfig } from "../../webpack.config.cjs";
+import { buildConfig } from "../../webpack.config";
 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 * as open from "open";
+import { generatePreviewUrl } from "@canva/cli";
 import type { Certificate } from "../ssl/ssl";
 import { createOrRetrieveCertificate } from "../ssl/ssl";
 
@@ -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/base/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/base/scripts/start/start.ts

@@ -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/base/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/base/{webpack.config.cjs → webpack.config.ts}

@@ -1,30 +1,36 @@
-require("dotenv").config();
-const path = require("path");
-const TerserPlugin = require("terser-webpack-plugin");
-const { DefinePlugin, optimize } = require("webpack");
-const chalk = require("chalk");
-const { transform } = require("@formatjs/ts-transformer");
+import type { Configuration } from "webpack";
+import { DefinePlugin, optimize } from "webpack";
+import * as path from "path";
+import * as TerserPlugin from "terser-webpack-plugin";
+import { transform } from "@formatjs/ts-transformer";
+import * as chalk from "chalk";
+import { config } from "dotenv";
+import { Configuration as DevServerConfiguration } from "webpack-dev-server";
 
-/**
- *
- * @param {Object} [options]
- * @param {string} [options.appEntry=./src/index.tsx]
- * @param {string} [options.backendHost]
- * @param {Object} [options.devConfig]
- * @param {number} [options.devConfig.port]
- * @param {boolean} [options.devConfig.enableHmr]
- * @param {boolean} [options.devConfig.enableHttps]
- * @param {string} [options.devConfig.appOrigin]
- * @param {string} [options.devConfig.appId] - Deprecated in favour of appOrigin
- * @param {string} [options.devConfig.certFile]
- * @param {string} [options.devConfig.keyFile]
- * @returns {Object}
- */
-function buildConfig({
+config();
+
+type DevConfig = {
+  port: number;
+  enableHmr: boolean;
+  enableHttps: boolean;
+  appOrigin?: string;
+  appId?: string; // Deprecated in favour of appOrigin
+  certFile?: string;
+  keyFile?: string;
+};
+
+export function buildConfig({
   devConfig,
   appEntry = path.join(process.cwd(), "src", "index.tsx"),
   backendHost = process.env.CANVA_BACKEND_HOST,
-} = {}) {
+  // For IN_HARNESS, refer to the following docs for more information: https://www.canva.dev/docs/apps/test-harness/
+  inHarness = process.env.IN_HARNESS === "true",
+}: {
+  devConfig?: DevConfig;
+  appEntry?: string;
+  backendHost?: string;
+  inHarness?: boolean;
+} = {}): Configuration & DevServerConfiguration {
   const mode = devConfig ? "development" : "production";
 
   if (!backendHost) {
@@ -45,9 +51,14 @@ function buildConfig({
   return {
     mode,
     context: path.resolve(process.cwd(), "./"),
-    entry: {
-      app: appEntry,
-    },
+    entry: inHarness
+      ? {
+          harness: path.join(process.cwd(), "harness", "harness.tsx"),
+          init: path.join(process.cwd(), "harness", "init.ts"),
+        }
+      : {
+          app: appEntry,
+        },
     target: "web",
     resolve: {
       alias: {
@@ -59,7 +70,7 @@ function buildConfig({
       extensions: [".ts", ".tsx", ".js", ".css", ".svg", ".woff", ".woff2"],
     },
     infrastructureLogging: {
-      level: "none",
+      level: inHarness ? "info" : "none",
     },
     module: {
       rules: [
@@ -173,32 +184,23 @@ function buildConfig({
       }),
       // Apps can only submit a single JS file via the developer portal
       new optimize.LimitChunkCountPlugin({ maxChunks: 1 }),
-    ],
+    ].filter(Boolean),
     ...buildDevConfig(devConfig),
   };
 }
 
-/**
- *
- * @param {Object} [options]
- * @param {number} [options.port]
- * @param {boolean} [options.enableHmr]
- * @param {boolean} [options.enableHttps]
- * @param {string} [options.appOrigin]
- * @param {string} [options.appId] - Deprecated in favour of appOrigin
- * @param {string} [options.certFile]
- * @param {string} [options.keyFile]
- * @returns {Object|null}
- */
-function buildDevConfig(options) {
+function buildDevConfig(options?: DevConfig): {
+  devtool?: string;
+  devServer?: DevServerConfiguration;
+} {
   if (!options) {
-    return null;
+    return {};
   }
 
   const { port, enableHmr, appOrigin, appId, enableHttps, certFile, keyFile } =
     options;
 
-  let devServer = {
+  let devServer: DevServerConfiguration = {
     server: enableHttps
       ? {
           type: "https",
@@ -265,6 +267,4 @@ function buildDevConfig(options) {
   };
 }
 
-module.exports = () => buildConfig();
-
-module.exports.buildConfig = buildConfig;
+export default buildConfig;

package/templates/common/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "canva": {
+      "command": "npx",
+      "args": ["-y", "@canva/cli@latest", "mcp"]
+    }
+  }
+}

package/templates/common/.gitignore.template

@@ -1,9 +1,8 @@
-.idea
-.ssl
-node_modules
 .DS_Store
-yarn-error.log
-dist
-secrets.json
 .env
+.idea
+.ssl
+*.log*
 **/*/db.json
+dist
+node_modules

package/templates/common/.nvmrc

@@ -0,0 +1 @@
+20.10.0

package/templates/common/.prettierrc

@@ -0,0 +1,21 @@
+{
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "endOfLine": "lf",
+  "htmlWhitespaceSensitivity": "css",
+  "insertPragma": false,
+  "singleAttributePerLine": false,
+  "bracketSameLine": false,
+  "jsxSingleQuote": false,
+  "printWidth": 80,
+  "proseWrap": "preserve",
+  "quoteProps": "as-needed",
+  "requirePragma": false,
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "useTabs": false,
+  "embeddedLanguageFormatting": "auto",
+  "experimentalTernaries": false
+}

package/templates/common/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  // For developers using vscode we recommend the following extensions. Following
+  // and listening to the formatting and linting guidelines can help with
+  // implementation quality and in some instances reduce app review timelines.
+  "recommendations": ["esbenp.prettier-vscode", "dbaeumer.vscode-eslint"]
+}

package/templates/common/.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "canva": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@canva/cli@latest", "mcp"]
+    }
+  }
+}

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.
 

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

package/templates/common/utils/backend/jwt_middleware/index.ts

@@ -0,0 +1 @@
+export { createJwtMiddleware } from "./jwt_middleware";