@canva/cli 0.0.1-beta.1

package/templates/base/webpack.config.cjs

@@ -0,0 +1,270 @@
+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");
+
+/**
+ *
+ * @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({
+  devConfig,
+  appEntry = path.join(process.cwd(), "src", "index.tsx"),
+  backendHost = process.env.CANVA_BACKEND_HOST,
+} = {}) {
+  const mode = devConfig ? "development" : "production";
+
+  if (!backendHost) {
+    console.error(
+      chalk.redBright.bold("BACKEND_HOST is undefined."),
+      `Refer to "Customizing the backend host" in the README.md for more information.`,
+    );
+    process.exit(-1);
+  } else if (backendHost.includes("localhost") && mode === "production") {
+    console.error(
+      chalk.redBright.bold(
+        "BACKEND_HOST should not be set to localhost for production builds!",
+      ),
+      `Refer to "Customizing the backend host" in the README.md for more information.`,
+    );
+  }
+
+  return {
+    mode,
+    context: path.resolve(process.cwd(), "./"),
+    entry: {
+      app: appEntry,
+    },
+    target: "web",
+    resolve: {
+      alias: {
+        assets: path.resolve(process.cwd(), "assets"),
+        utils: path.resolve(process.cwd(), "utils"),
+        styles: path.resolve(process.cwd(), "styles"),
+        src: path.resolve(process.cwd(), "src"),
+      },
+      extensions: [".ts", ".tsx", ".js", ".css", ".svg", ".woff", ".woff2"],
+    },
+    infrastructureLogging: {
+      level: "none",
+    },
+    module: {
+      rules: [
+        {
+          test: /\.tsx?$/,
+          exclude: /node_modules/,
+          use: [
+            {
+              loader: "ts-loader",
+              options: {
+                transpileOnly: true,
+                getCustomTransformers() {
+                  return {
+                    before: [
+                      transform({
+                        overrideIdFn: "[sha512:contenthash:base64:6]",
+                      }),
+                    ],
+                  };
+                },
+              },
+            },
+          ],
+        },
+        {
+          test: /\.css$/,
+          exclude: /node_modules/,
+          use: [
+            "style-loader",
+            {
+              loader: "css-loader",
+              options: {
+                modules: true,
+              },
+            },
+            {
+              loader: "postcss-loader",
+              options: {
+                postcssOptions: {
+                  plugins: [require("cssnano")({ preset: "default" })],
+                },
+              },
+            },
+          ],
+        },
+        {
+          test: /\.(png|jpg|jpeg)$/i,
+          type: "asset/inline",
+        },
+        {
+          test: /\.(woff|woff2)$/,
+          type: "asset/inline",
+        },
+        {
+          test: /\.svg$/,
+          oneOf: [
+            {
+              issuer: /\.[jt]sx?$/,
+              resourceQuery: /react/, // *.svg?react
+              use: ["@svgr/webpack", "url-loader"],
+            },
+            {
+              type: "asset/resource",
+              parser: {
+                dataUrlCondition: {
+                  maxSize: 200,
+                },
+              },
+            },
+          ],
+        },
+        {
+          test: /\.css$/,
+          include: /node_modules/,
+          use: [
+            "style-loader",
+            "css-loader",
+            {
+              loader: "postcss-loader",
+              options: {
+                postcssOptions: {
+                  plugins: [require("cssnano")({ preset: "default" })],
+                },
+              },
+            },
+          ],
+        },
+      ],
+    },
+    optimization: {
+      minimizer: [
+        new TerserPlugin({
+          terserOptions: {
+            format: {
+              // Turned on because emoji and regex is not minified properly using default
+              // https://github.com/facebook/create-react-app/issues/2488
+              ascii_only: true,
+            },
+          },
+        }),
+      ],
+    },
+    output: {
+      filename: `[name].js`,
+      path: path.resolve(process.cwd(), "dist"),
+      clean: true,
+    },
+    plugins: [
+      new DefinePlugin({
+        BACKEND_HOST: JSON.stringify(backendHost),
+      }),
+      // Apps can only submit a single JS file via the developer portal
+      new optimize.LimitChunkCountPlugin({ maxChunks: 1 }),
+    ],
+    ...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) {
+  if (!options) {
+    return null;
+  }
+
+  const { port, enableHmr, appOrigin, appId, enableHttps, certFile, keyFile } =
+    options;
+
+  let devServer = {
+    server: enableHttps
+      ? {
+          type: "https",
+          options: {
+            cert: certFile,
+            key: keyFile,
+          },
+        }
+      : "http",
+    host: "localhost",
+    historyApiFallback: {
+      rewrites: [{ from: /^\/$/, to: "/app.js" }],
+    },
+    port,
+    client: {
+      logging: "verbose",
+    },
+    static: {
+      directory: path.resolve(process.cwd(), "assets"),
+      publicPath: "/assets",
+    },
+  };
+
+  if (enableHmr && appOrigin) {
+    devServer = {
+      ...devServer,
+      allowedHosts: new URL(appOrigin).hostname,
+      headers: {
+        "Access-Control-Allow-Origin": appOrigin,
+        "Access-Control-Allow-Credentials": "true",
+        "Access-Control-Allow-Private-Network": "true",
+      },
+    };
+  } else if (enableHmr && appId) {
+    // Deprecated - App ID should not be used to configure HMR in the future and can be safely removed
+    // after a few months.
+
+    console.warn(
+      "Enabling Hot Module Replacement (HMR) with an App ID is deprecated, please see the README.md on how to update.",
+    );
+
+    const appDomain = `app-${appId.toLowerCase().trim()}.canva-apps.com`;
+    devServer = {
+      ...devServer,
+      allowedHosts: appDomain,
+      headers: {
+        "Access-Control-Allow-Origin": `https://${appDomain}`,
+        "Access-Control-Allow-Credentials": "true",
+        "Access-Control-Allow-Private-Network": "true",
+      },
+    };
+  } else {
+    if (enableHmr && !appOrigin) {
+      console.warn(
+        "Attempted to enable Hot Module Replacement (HMR) without configuring App Origin... Disabling HMR.",
+      );
+    }
+    devServer.webSocketServer = false;
+  }
+
+  return {
+    devtool: "source-map",
+    devServer,
+  };
+}
+
+module.exports = () => buildConfig();
+
+module.exports.buildConfig = buildConfig;

package/templates/common/.env.template

@@ -0,0 +1,6 @@
+CANVA_FRONTEND_PORT=8080
+CANVA_BACKEND_PORT=3001
+CANVA_BACKEND_HOST=http://localhost:3001 # TODO: replace this with your production URL before submitting your app
+CANVA_APP_ID=YOUR_APP_ID_HERE # TODO: Add your app's ID here to configure your backend for JWT verification
+CANVA_APP_ORIGIN=# TODO: Add your app's origin here from the "Developer Portal -> Configure your app -> App Origin" to enable HMR
+CANVA_HMR_ENABLED=FALSE # TODO: set to TRUE to enable HMR 

package/templates/common/.gitignore.template

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

package/templates/common/LICENSE.md

@@ -0,0 +1,48 @@
+# A message from Canva
+
+By making these software components available to you, our goal is to give you
+the right to use the components to build your apps for Canva's ecosystem. See
+below for the specific licence terms that apply to your use.
+
+# Licence
+
+Canva Pty Ltd (ACN 158 929 938) ("Canva") owns the copyright in the software and
+associated documentation files to which this Licence relates (each a "Software
+Component"). Canva reserves all of its rights.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+the Software Components ("You"), to use the Software Components, but strictly
+subject to the following restrictions and conditions:
+
+1. You must only use the Software Components and any Derivative on the Canva
+   Platform.
+
+2. You must only use the Software Components and any Derivative for the purpose
+   of building or updating Permitted Apps, and for no other purpose.
+
+3. You must include a copy of this Licence in all copies of any Software
+   Component and Derivative.
+
+4. To the fullest extent permitted by law, the Software Components are provided
+   "as is", without warranty of any kind, express or implied, including but not
+   limited to the warranties of merchantability, fitness for a particular
+   purpose and non-infringement. To the fullest extent permitted by law, in no
+   event shall the authors or copyright holders be liable for any claim,
+   damages or other liability, whether in an action of contract, tort or
+   otherwise, arising from, out of or in connection with the Software Components
+   or any Derivative, or the use of or other dealings in the Software Components
+   or any Derivative.
+
+5. In this Licence:
+
+   (a) "Canva Platform" means the visual communications platform owned and
+   operated by Canva that is made available on Canva.com (as well as any
+   sub-domains and international versions) and via mobile applications, desktop
+   applications, and in other forms provided or made available by Canva;
+
+   (b) "Derivative" means any software, document or other material that: (i)
+   contains any Software Component; and/or (ii) comprises or contains a
+   derivative, adaptation or substantial part of any Software Component; and
+
+   (c) "Permitted App" means a software application that is solely offered to
+   end-users on the Canva Platform.

package/templates/common/README.md

@@ -0,0 +1,250 @@
+# Canva App
+
+Welcome to your Canva App! 🎉
+
+This is a starting point for your app using your chosen template. The complete documentation for the platform is at [canva.dev/docs/apps](https://www.canva.dev/docs/apps/).
+
+**Note:** This code and documentation assumes some experience with TypeScript and React.
+
+## Requirements
+
+- Node.js `v18` or `v20.10.0`
+- npm `v9` or `v10`
+
+**Note:** To make sure you're running the correct version of Node.js, we recommend using a version manager, such as [nvm](https://github.com/nvm-sh/nvm#intro). The [.nvmrc](/.nvmrc) file in the root directory of this repo will ensure the correct version is used once you run `nvm install`.
+
+## Quick start
+
+```bash
+npm install
+```
+
+## Running your Canva App
+
+### Step 1: Start the local development server
+
+To start the boilerplate's development server, run the following command:
+
+```bash
+npm start
+```
+
+The server becomes available at <http://localhost:8080>.
+
+The app's source code is in the `src/app.tsx` file.
+
+### Step 2: Preview the app
+
+The local development server only exposes a JavaScript bundle, so you can't preview an app by visiting <http://localhost:8080>. You can only preview an app via the Canva editor.
+
+To preview an app:
+
+1. Create an app via the [Developer Portal](https://www.canva.com/developers/apps).
+2. Select **App source > Development URL**.
+3. In the **Development URL** field, enter the URL of the development server.
+4. Click **Preview**. This opens the Canva editor (and the app) in a new tab.
+5. Click **Open**. (This screen only appears when using an app for the first time.)
+
+The app will appear in the side panel.
+
+<details>
+  <summary>Previewing apps in Safari</summary>
+
+By default, the development server is not HTTPS-enabled. This is convenient, as there's no need for a security certificate, but it prevents apps from being previewed in Safari.
+
+**Why Safari requires the development server to be HTTPS-enabled?**
+
+Canva itself is served via HTTPS and most browsers prevent HTTPS pages from loading scripts via non-HTTPS connections. Chrome and Firefox make exceptions for local servers, such as `localhost`, but Safari does not, so if you're using Safari, the development server must be HTTPS-enabled.
+
+To learn more, see [Loading mixed-content resources](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content#loading_mixed-content_resources).
+
+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>.
+
+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.
+
+</details>
+
+### (Optional) Step 3: Enable Hot Module Replacement
+
+By default, every time you make a change to an app, you have to reload the entire app to see the results of those changes. If you enable [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) (HMR), changes will be reflected without a full reload, which significantly speeds up the development loop.
+
+**Note:** HMR does **not** work while running the development server in a Docker container.
+
+To enable HMR:
+
+1. Navigate to an app via the [Your apps](https://www.canva.com/developers/apps).
+2. Select **Configure your app**.
+3. Copy the value from the **App origin** field. This value is unique to each app and cannot be customized.
+4. In the root directory, open the `.env` file.
+5. Set the `CANVA_APP_ORIGIN` environment variable to the value copied from the **App origin** field:
+
+   ```bash
+   CANVA_APP_ORIGIN=# YOUR APP ORIGIN GOES HERE
+   ```
+
+6. Set the `CANVA_HMR_ENABLED` environment variable to `true`:
+
+   ```bash
+   CANVA_HMR_ENABLED=true
+   ```
+
+7. Restart the local development server.
+8. Reload the app manually to ensure that HMR takes effect.
+
+## Running an app's backend
+
+Some templates provide an example backend. This backend is defined in the template's `backend/server.ts` file, automatically starts when the `npm start` command is run, and becomes available at <http://localhost:3001>.
+
+To run templates that have a backend:
+
+1. Navigate to the [Your apps](https://www.canva.com/developers/apps) page.
+2. Copy the ID of an app from the **App ID** column.
+3. In the starter kit's `.env` file, set `CANVA_APP_ID` to the ID of the app.
+
+   For example:
+
+   ```bash
+   CANVA_APP_ID=AABBccddeeff
+   CANVA_APP_ORIGIN=#
+   CANVA_BACKEND_PORT=3001
+   CANVA_FRONTEND_PORT=8080
+   CANVA_BACKEND_HOST=http://localhost:3001
+   CANVA_HMR_ENABLED=FALSE
+   ```
+
+4. Start the app:
+
+   ```bash
+   npm start
+   ```
+
+The ID of the app must be explicitly defined because it's required to [send and verify HTTP requests](https://www.canva.dev/docs/apps/verifying-http-requests/). If you don't set up the ID in the `.env` file, an error will be thrown when attempting to run the example.
+
+## Customizing the backend host
+
+If your app has a backend, the URL of the server likely depends on whether it's a development or production build. For example, during development, the backend is probably running on a localhost URL, but once the app's in production, the backend needs to be exposed to the internet.
+
+To more easily customize the URL of the server:
+
+1. Open the `.env` file in the text editor of your choice.
+2. Set the `CANVA_BACKEND_HOST` environment variable to the URL of the server.
+3. When sending a request, use `BACKEND_HOST` as the base URL:
+
+   ```ts
+   const response = await fetch(`${BACKEND_HOST}/custom-route`);
+   ```
+
+   **Note:** `BACKEND_HOST` is a global constant that contains the value of the `CANVA_BACKEND_HOST` environment variable. The variable is made available to the app via webpack and does not need to be imported.
+
+4. Before bundling the app for production, update `CANVA_BACKEND_HOST` to point to the production backend.
+
+## Configure ngrok (optional)
+
+If your app requires authentication with a third party service, your server needs to be exposed via a publicly available URL, so that Canva can send requests to it.
+This step explains how to do this with [ngrok](https://ngrok.com/).
+
+**Note:** ngrok is a useful tool, but it has inherent security risks, such as someone figuring out the URL of your server and accessing proprietary information. Be mindful of the risks, and if you're working as part of an organization, talk to your IT department.
+You must replace ngrok urls with hosted API endpoints for production apps.
+
+To use ngrok, you'll need to do the following:
+
+1. Sign up for a ngrok account at <https://ngrok.com/>.
+2. Locate your ngrok [authtoken](https://dashboard.ngrok.com/get-started/your-authtoken).
+3. Set an environment variable for your authtoken, using the command line. Replace `<YOUR_AUTH_TOKEN>` with your actual ngrok authtoken:
+
+   For macOS and Linux:
+
+   ```bash
+   export NGROK_AUTHTOKEN=<YOUR_AUTH_TOKEN>
+   ```
+
+   For Windows PowerShell:
+
+   ```shell
+   $Env:NGROK_AUTHTOKEN = "<YOUR_AUTH_TOKEN>"
+   ```
+
+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/jest.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+
+export default {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testRegex: "(/tests/.*|(\\.|/)(tests))\\.ts?$",
+  modulePathIgnorePatterns: ["./internal/", "./node_modules/"],
+};

package/templates/dam/backend/database/database.ts

@@ -0,0 +1,42 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+
+/**
+ * This file creates a "database" out of a JSON file. It's only for
+ * demonstration purposes. A real app should use a real database.
+ */
+const DATABASE_FILE_PATH = path.join(__dirname, "db.json");
+
+interface Database<T> {
+  read(): Promise<T>;
+  write(data: T): Promise<void>;
+}
+
+export class JSONFileDatabase<T> implements Database<T> {
+  constructor(private readonly seedData: T) {}
+
+  // Creates a database file if one doesn't already exist
+  private async init(): Promise<void> {
+    try {
+      // Do nothing, since the database is initialized
+      await fs.stat(DATABASE_FILE_PATH);
+    } catch {
+      const file = JSON.stringify(this.seedData);
+      await fs.writeFile(DATABASE_FILE_PATH, file);
+    }
+  }
+
+  // Loads and parses the database file
+  async read(): Promise<T> {
+    await this.init();
+    const file = await fs.readFile(DATABASE_FILE_PATH, "utf8");
+    return JSON.parse(file);
+  }
+
+  // Overwrites the database file with provided data
+  async write(data: T): Promise<void> {
+    await this.init();
+    const file = JSON.stringify(data);
+    await fs.writeFile(DATABASE_FILE_PATH, file);
+  }
+}