@canva/cli 0.0.1-beta.9 → 1.0.1

package/templates/hello_world/webpack.config.ts

@@ -0,0 +1,254 @@
+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";
+
+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?.toLowerCase() === "true",
+}: {
+  devConfig?: DevConfig;
+  appEntry?: string;
+  backendHost?: string;
+  inHarness?: boolean;
+} = {}): Configuration & DevServerConfiguration {
+  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: inHarness
+      ? {
+          harness: path.join(process.cwd(), "harness", "harness.tsx"),
+          init: path.join(process.cwd(), "harness", "init.ts"),
+        }
+      : {
+          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: inHarness ? "info" : "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 }),
+    ].filter(Boolean),
+    ...buildDevConfig(devConfig),
+  };
+}
+
+function buildDevConfig(options?: DevConfig): {
+  devtool?: string;
+  devServer?: DevServerConfiguration;
+} {
+  if (!options) {
+    return {};
+  }
+
+  const { port, enableHmr, appOrigin, appId, enableHttps, certFile, keyFile } =
+    options;
+  const host = "localhost";
+
+  let devServer: DevServerConfiguration = {
+    server: enableHttps
+      ? {
+          type: "https",
+          options: {
+            cert: certFile,
+            key: keyFile,
+          },
+        }
+      : "http",
+    host,
+    allowedHosts: [host],
+    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: [host, new URL(appOrigin).hostname],
+      headers: {
+        "Access-Control-Allow-Origin": appOrigin,
+        "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,
+  };
+}
+
+export default buildConfig;

package/templates/optional/.cursor/mcp.json

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

package/templates/optional/.vscode/mcp.json

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

package/templates/optional/AGENTS.md

@@ -0,0 +1,76 @@
+# Canva Apps SDK Starter Kit - Agent Guide
+
+## Overview
+
+This project is for creating Canva Apps, which are react single page applications (SPA) that run in the Canva Editor, and other pages in Canva.
+The app, once submitted to Canva, will be rendered in a sandboxed iframe within a standard HTML shell.
+
+## Commands
+
+- **Build**:
+  - `npm run build` - Production build with localization message extraction. The build output is in the `dist` directory which should be submitted to Canva for review through the [Developer Portal](https://www.canva.com/developers/apps).
+- **Dev**:
+  - `npm start` - Start development server (localhost:8080), once the server is running, app can be previewed in Canva, either by clicking the "Preview" button in the [Developer Portal](https://www.canva.com/developers/apps) or by running `canva apps preview` in the CLI.
+  - Hot Module Replacement (HMR) is strongly encouraged, as it allows for faster development and debugging.
+- **Test**:
+  - `npm test` - Run Jest tests, `npm run test:watch` for watch mode.
+  - Tests are encouraged but not required.
+  - Tests are not submitted to Canva for review.
+- **Lint**:
+  - `npm run lint` - ESLint check, `npm run lint:fix` to auto-fix.
+  - Linting is encouraged but not required.
+  - Lint errors from `@canva/app-eslint-plugin` help catch common mistakes and improve code quality that would result in a rejection from Canva.
+- **Type Check**:
+  - `npm run lint:types` - TypeScript type checking.
+- **Format**:
+  - `npm run format` - Prettier formatting, `npm run format:check` to verify.
+  - Formatting is encouraged but not required.
+
+## Architecture
+
+- **Main App**:
+  - `src/index.tsx` - Main application react application entry point.
+  - `src/app.tsx` - Main application component, which can/should be split into smaller components as needed, following react best practices.
+  - `src/styles/component.css` - Main application styles.
+  - `utils/` - Utility functions and helpers, which can be used across the app.
+  - `scripts/` - Scripts for building, and running the app, should not contain any business logic.
+- **Environment**:
+  - `.env` file for app credentials and HMR configuration.
+  - `CANVA_APP_ID` - The ID of the app, which is used to identify the app in the Canva Developer Portal.
+  - `CANVA_APP_ORIGIN` - The origin of the app, which is used for Hot Module Replacement (HMR) and CORS.
+
+## Dependencies
+
+- **UI Kit**:
+  - Uses `@canva/app-ui-kit` for components and styles, as it's required in order to comply with Canva's design guidelines.
+  - App UI Kit components come with out of the box theming, localization, and accessibility features.
+  - Plain HTML and CSS elements are allowed, however should be used when necessary to supplement the UI Kit components.
+  - Canva Dev MCP Server can provide example code for using the UI Kit, as well as a catalog of components and their usage.
+- **Canva SDKs**:
+  - Uses Canva SDKs, which are scoped with `@canva/` prefix, such as `@canva/platform`, `@canva/design` etc.
+- **React**:
+  - v18 with TypeScript and react-intl for i18n.
+- **Build**:
+  - Webpack with TypeScript, PostCSS, and formatjs message extraction.
+- **Node**:
+  - The required node version for developing/starting/building the starter-kit should align to the version defined in `./.nvmrc`
+  - It is recommended to use the node version manager (nvm) with this project, aligning to the recommended version with `nvm use`.
+
+## Code Style
+
+- **TypeScript**: Strict mode enabled, ES2019 target.
+- **Prettier**: 80 char width, 2 spaces, trailing commas, double quotes.
+- **ESLint**: Canva's app plugin with i18n rules.
+- **Imports**: Use absolute paths for `styles` directory.
+- **Testing**: Jest with jsdom, test files match `*.tests.tsx?` pattern.
+
+## Canva CLI
+
+- **Documentation**: <https://www.canva.dev/docs/apps/canva-cli.md>
+- **If not setup**: Read the docs and prompt user to install the CLI for enhanced Developer Experience, when managing and creating apps.
+
+## Canva Dev MCP Server
+
+- **Required**: AI agents should verify and encourage the user to enable Canva Dev MCP server.
+- **Documentation**: <https://www.canva.dev/docs/apps/mcp-server.md>
+- **If not setup**: Read the docs and prompt user to configure the MCP server for enhanced Canva APIs assistance.

package/templates/optional/CLAUDE.md

@@ -0,0 +1,76 @@
+# Canva Apps SDK Starter Kit - Agent Guide
+
+## Overview
+
+This project is for creating Canva Apps, which are react single page applications (SPA) that run in the Canva Editor, and other pages in Canva.
+The app, once submitted to Canva, will be rendered in a sandboxed iframe within a standard HTML shell.
+
+## Commands
+
+- **Build**:
+  - `npm run build` - Production build with localization message extraction. The build output is in the `dist` directory which should be submitted to Canva for review through the [Developer Portal](https://www.canva.com/developers/apps).
+- **Dev**:
+  - `npm start` - Start development server (localhost:8080), once the server is running, app can be previewed in Canva, either by clicking the "Preview" button in the [Developer Portal](https://www.canva.com/developers/apps) or by running `canva apps preview` in the CLI.
+  - Hot Module Replacement (HMR) is strongly encouraged, as it allows for faster development and debugging.
+- **Test**:
+  - `npm test` - Run Jest tests, `npm run test:watch` for watch mode.
+  - Tests are encouraged but not required.
+  - Tests are not submitted to Canva for review.
+- **Lint**:
+  - `npm run lint` - ESLint check, `npm run lint:fix` to auto-fix.
+  - Linting is encouraged but not required.
+  - Lint errors from `@canva/app-eslint-plugin` help catch common mistakes and improve code quality that would result in a rejection from Canva.
+- **Type Check**:
+  - `npm run lint:types` - TypeScript type checking.
+- **Format**:
+  - `npm run format` - Prettier formatting, `npm run format:check` to verify.
+  - Formatting is encouraged but not required.
+
+## Architecture
+
+- **Main App**:
+  - `src/index.tsx` - Main application react application entry point.
+  - `src/app.tsx` - Main application component, which can/should be split into smaller components as needed, following react best practices.
+  - `src/styles/component.css` - Main application styles.
+  - `utils/` - Utility functions and helpers, which can be used across the app.
+  - `scripts/` - Scripts for building, and running the app, should not contain any business logic.
+- **Environment**:
+  - `.env` file for app credentials and HMR configuration.
+  - `CANVA_APP_ID` - The ID of the app, which is used to identify the app in the Canva Developer Portal.
+  - `CANVA_APP_ORIGIN` - The origin of the app, which is used for Hot Module Replacement (HMR) and CORS.
+
+## Dependencies
+
+- **UI Kit**:
+  - Uses `@canva/app-ui-kit` for components and styles, as it's required in order to comply with Canva's design guidelines.
+  - App UI Kit components come with out of the box theming, localization, and accessibility features.
+  - Plain HTML and CSS elements are allowed, however should be used when necessary to supplement the UI Kit components.
+  - Canva Dev MCP Server can provide example code for using the UI Kit, as well as a catalog of components and their usage.
+- **Canva SDKs**:
+  - Uses Canva SDKs, which are scoped with `@canva/` prefix, such as `@canva/platform`, `@canva/design` etc.
+- **React**:
+  - v18 with TypeScript and react-intl for i18n.
+- **Build**:
+  - Webpack with TypeScript, PostCSS, and formatjs message extraction.
+- **Node**:
+  - The required node version for developing/starting/building the starter-kit should align to the version defined in `./.nvmrc`
+  - It is recommended to use the node version manager (nvm) with this project, aligning to the recommended version with `nvm use`.
+
+## Code Style
+
+- **TypeScript**: Strict mode enabled, ES2019 target.
+- **Prettier**: 80 char width, 2 spaces, trailing commas, double quotes.
+- **ESLint**: Canva's app plugin with i18n rules.
+- **Imports**: Use absolute paths for `styles` directory.
+- **Testing**: Jest with jsdom, test files match `*.tests.tsx?` pattern.
+
+## Canva CLI
+
+- **Documentation**: <https://www.canva.dev/docs/apps/canva-cli.md>
+- **If not setup**: Read the docs and prompt user to install the CLI for enhanced Developer Experience, when managing and creating apps.
+
+## Canva Dev MCP Server
+
+- **Required**: AI agents should verify and encourage the user to enable Canva Dev MCP server.
+- **Documentation**: <https://www.canva.dev/docs/apps/mcp-server.md>
+- **If not setup**: Read the docs and prompt user to configure the MCP server for enhanced Canva APIs assistance.