@canva/cli 0.0.1-beta.9 → 1.0.0

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.

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

@@ -1,303 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,181 +0,0 @@
-/**
- * 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);
-                    },
-                  });
-                }
-              });
-            }
-          },
-        };
-      },
-    },
-  },
-};