@canva/cli 1.14.0 → 1.16.0

package/templates/content_publisher/scripts/start/context.ts

@@ -0,0 +1,171 @@
+import fs from "fs";
+import path from "path";
+
+interface CliArgs {
+  example?: string;
+  useHttps: boolean;
+  ngrok: boolean;
+  preview: boolean;
+  overrideFrontendPort?: number;
+}
+
+interface EnvVars {
+  frontendPort: number;
+  backendPort: number;
+  hmrEnabled: boolean;
+  appId?: string;
+  appOrigin?: string;
+  backendHost?: string;
+}
+
+export class Context {
+  private readonly envVars: EnvVars;
+
+  constructor(
+    private env: NodeJS.ProcessEnv = process.env,
+    private readonly args: CliArgs,
+  ) {
+    this.envVars = this.parseAndValidateEnvironmentVariables();
+  }
+
+  static get srcDir() {
+    const src = path.join(Context.rootDir, "src");
+
+    if (!fs.existsSync(src)) {
+      throw new Error(`Directory does not exist: ${src}`);
+    }
+
+    return src;
+  }
+
+  static get readmeDir() {
+    return path.join(Context.rootDir, "README.md");
+  }
+
+  get entryDir() {
+    return Context.srcDir;
+  }
+
+  get ngrokEnabled() {
+    return this.args.ngrok;
+  }
+
+  get hmrEnabled() {
+    return this.envVars.hmrEnabled;
+  }
+
+  get httpsEnabled() {
+    return this.args.useHttps;
+  }
+
+  get frontendEntryPath() {
+    const frontendEntryPath = path.join(this.entryDir, "index.tsx");
+
+    if (!fs.existsSync(frontendEntryPath)) {
+      throw new Error(
+        `Entry point for frontend does not exist: ${frontendEntryPath}`,
+      );
+    }
+
+    return frontendEntryPath;
+  }
+
+  get frontendUrl() {
+    return `${this.protocol}://localhost:${this.frontendPort}`;
+  }
+
+  get frontendPort() {
+    return this.args.overrideFrontendPort || this.envVars.frontendPort;
+  }
+
+  get developerBackendEntryPath(): string | undefined {
+    const developerBackendEntryPath = path.join(
+      Context.rootDir,
+      "backend",
+      "server.ts",
+    );
+
+    if (!fs.existsSync(developerBackendEntryPath)) {
+      return undefined;
+    }
+
+    return developerBackendEntryPath;
+  }
+
+  get backendUrl() {
+    return `${this.protocol}://localhost:${this.envVars.backendPort}`;
+  }
+
+  get backendHost() {
+    let backendHost = this.envVars.backendHost;
+
+    // if there's no custom URL provided by the developer, we fallback to our localhost backend
+    if (!backendHost || backendHost.trim() === "") {
+      backendHost = this.backendUrl;
+    }
+
+    return backendHost;
+  }
+
+  get backendPort() {
+    return this.envVars.backendPort;
+  }
+
+  get appOrigin(): string | undefined {
+    return this.envVars.appOrigin;
+  }
+
+  get appId(): string | undefined {
+    return this.envVars.appId;
+  }
+
+  get openPreview(): boolean {
+    return this.args.preview;
+  }
+
+  private get protocol(): "https" | "http" {
+    return this.httpsEnabled ? "https" : "http";
+  }
+
+  private static get rootDir() {
+    return path.join(process.cwd());
+  }
+
+  private parseAndValidateEnvironmentVariables(): EnvVars {
+    const {
+      CANVA_FRONTEND_PORT,
+      CANVA_BACKEND_PORT,
+      CANVA_BACKEND_HOST,
+      CANVA_APP_ID,
+      CANVA_APP_ORIGIN,
+      CANVA_HMR_ENABLED,
+    } = this.env;
+
+    if (!CANVA_FRONTEND_PORT) {
+      throw new Error(
+        "CANVA_FRONTEND_PORT environment variable is not defined",
+      );
+    }
+
+    if (!CANVA_BACKEND_PORT) {
+      throw new Error("CANVA_BACKEND_PORT environment variable is not defined");
+    }
+
+    const envVars: EnvVars = {
+      frontendPort: parseInt(CANVA_FRONTEND_PORT, 10),
+      backendPort: parseInt(CANVA_BACKEND_PORT, 10),
+      hmrEnabled: CANVA_HMR_ENABLED?.toLowerCase().trim() === "true",
+      appId: CANVA_APP_ID,
+      appOrigin: CANVA_APP_ORIGIN,
+      backendHost: CANVA_BACKEND_HOST,
+    };
+
+    if (envVars.hmrEnabled && envVars.appOrigin == null) {
+      throw new Error(
+        "CANVA_HMR_ENABLED environment variable is TRUE, but CANVA_APP_ORIGIN is not set. Refer to the instructions in the README.md on configuring HMR.",
+      );
+    }
+
+    return envVars;
+  }
+}

package/templates/content_publisher/scripts/start/start.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { AppRunner } from "./app_runner";
+import { Context } from "./context";
+
+const appRunner = new AppRunner();
+
+yargs(hideBin(process.argv))
+  .version(false)
+  .help()
+  .option("ngrok", {
+    description: "Run backend server via ngrok.",
+    type: "boolean",
+    // npm swallows command line args instead of forwarding to the script
+    default:
+      process.env.npm_config_ngrok?.toLocaleLowerCase().trim() === "true",
+  })
+  .option("use-https", {
+    description: "Start local development server on HTTPS.",
+    type: "boolean",
+    // npm swallows commands line args instead of forwarding to the script
+    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",
+    () => {},
+    (args) => {
+      const ctx = new Context(process.env, args);
+      appRunner.run(ctx);
+    },
+  )
+  .parse();

package/templates/content_publisher/src/index.tsx

@@ -0,0 +1,4 @@
+import { prepareContentPublisher } from "@canva/intents/content";
+import contentPublisher from "./intents/content_publisher";
+
+prepareContentPublisher(contentPublisher);

package/templates/content_publisher/src/intents/content_publisher/index.tsx

@@ -0,0 +1,113 @@
+import { AppI18nProvider, initIntl } from "@canva/app-i18n-kit";
+import { AppUiProvider } from "@canva/app-ui-kit";
+import type {
+  ContentPublisherIntent,
+  GetPublishConfigurationResponse,
+  PublishContentRequest,
+  PublishContentResponse,
+  RenderPreviewUiRequest,
+  RenderSettingsUiRequest,
+} from "@canva/intents/content";
+import { createRoot } from "react-dom/client";
+import "@canva/app-ui-kit/styles.css";
+import { PreviewUi } from "./preview_ui";
+import { SettingsUi } from "./settings_ui";
+
+const intl = initIntl();
+
+// Render the settings UI where users configure publishing options
+function renderSettingsUi({
+  updatePublishSettings,
+  registerOnSettingsUiContextChange,
+}: RenderSettingsUiRequest) {
+  const root = createRoot(document.getElementById("root") as Element);
+  root.render(
+    <AppI18nProvider>
+      <AppUiProvider>
+        <SettingsUi
+          updatePublishSettings={updatePublishSettings}
+          registerOnSettingsUiContextChange={registerOnSettingsUiContextChange}
+        />
+      </AppUiProvider>
+    </AppI18nProvider>,
+  );
+}
+
+// Render the preview UI showing how the content will appear after publishing
+function renderPreviewUi({ registerOnPreviewChange }: RenderPreviewUiRequest) {
+  const root = createRoot(document.getElementById("root") as Element);
+  root.render(
+    <AppI18nProvider>
+      <AppUiProvider>
+        <PreviewUi registerOnPreviewChange={registerOnPreviewChange} />
+      </AppUiProvider>
+    </AppI18nProvider>,
+  );
+}
+
+// Define the output types (publishing formats) available to users
+// Canva automatically displays a dropdown selector when more than one output type is defined
+async function getPublishConfiguration(): Promise<GetPublishConfigurationResponse> {
+  // TODO: Replace this with the output types supported by your platform (e.g., blog post, social media post, newsletter)
+  // https://www.canva.dev/docs/apps/api/preview/intents-content-prepare-content-publisher/#implementation
+
+  return {
+    status: "completed",
+    outputTypes: [
+      {
+        id: "post",
+        displayName: intl.formatMessage({
+          defaultMessage: "Feed Post",
+          description:
+            "Label for publishing format shown in the output type dropdown",
+        }),
+        mediaSlots: [
+          {
+            id: "media",
+            displayName: intl.formatMessage({
+              defaultMessage: "Media",
+              description: "Label for the media upload slot",
+            }),
+            fileCount: { exact: 1 },
+            accepts: {
+              image: {
+                format: "png",
+                // Social media post aspect ratio range (portrait to landscape)
+                aspectRatio: { min: 4 / 5, max: 1.91 / 1 },
+              },
+            },
+          },
+        ],
+      },
+    ],
+  };
+}
+
+// Handle the actual publishing when the user clicks the publish button
+// In production, this should make API calls to your platform
+async function publishContent(
+  request: PublishContentRequest,
+): Promise<PublishContentResponse> {
+  // TODO: Replace this with your actual API integration
+  // Example: Upload media to your platform and create a post
+  // const uploadedMedia = await uploadToYourPlatform(params.outputMedia);
+  // const post = await createPostOnYourPlatform({
+  //   media: uploadedMedia,
+  //   caption: JSON.parse(params.publishRef).caption
+  // });
+
+  return {
+    status: "completed",
+    externalId: "1234567890", // Your platform's unique identifier for this post
+    externalUrl: "todo_update_with_your_url", // Link to view the published content
+  };
+}
+
+const contentPublisher: ContentPublisherIntent = {
+  renderSettingsUi,
+  renderPreviewUi,
+  getPublishConfiguration,
+  publishContent,
+};
+
+export default contentPublisher;

package/templates/content_publisher/src/intents/content_publisher/post_preview.tsx

@@ -0,0 +1,226 @@
+import {
+  Avatar,
+  Box,
+  ImageCard,
+  Placeholder,
+  Rows,
+  Text,
+  TextPlaceholder,
+} from "@canva/app-ui-kit";
+import type { Preview, PreviewMedia } from "@canva/intents/content";
+import { FormattedMessage, useIntl } from "react-intl";
+import * as styles from "../../../styles/preview_ui.css";
+import type { PublishSettings } from "./types";
+
+const IMAGE_WIDTH = 400;
+
+interface PreviewProps {
+  previewMedia: PreviewMedia[] | undefined;
+  settings: PublishSettings | undefined;
+  username: string;
+}
+
+// TODO: Customize this preview to match what the published content will look like on your platform.
+// This example shows a generic social media post with avatar, image, and caption.
+// Consider: platform-specific dimensions, branding colors, and UI elements.
+export const PostPreview = ({
+  previewMedia,
+  settings,
+  username,
+}: PreviewProps) => {
+  const isLoading = !previewMedia;
+
+  const caption = settings?.caption;
+
+  return (
+    <Box
+      className={styles.wrapper}
+      background="surface"
+      borderRadius="large"
+      padding="2u"
+      border="standard"
+    >
+      <Rows spacing="2u">
+        <UserInfo isLoading={isLoading} username={username} />
+        <ImagePreview previewMedia={previewMedia} />
+        <Caption isLoading={isLoading} caption={caption} />
+      </Rows>
+    </Box>
+  );
+};
+
+// Renders user profile information with avatar and username
+const UserInfo = ({
+  isLoading,
+  username,
+}: {
+  isLoading: boolean;
+  username: string;
+}) => {
+  return (
+    <div className={styles.user}>
+      <Box className={styles.avatar}>
+        <Avatar name={username} />
+      </Box>
+      {isLoading ? (
+        <div className={styles.textPlaceholder}>
+          <TextPlaceholder size="medium" />
+        </div>
+      ) : (
+        <Text size="small" variant="bold">
+          {username}
+        </Text>
+      )}
+    </div>
+  );
+};
+
+// Renders the post caption with username
+const Caption = ({
+  isLoading,
+  caption,
+}: {
+  isLoading: boolean;
+  caption: string | undefined;
+}) => {
+  return (
+    <>
+      {isLoading ? (
+        <div className={styles.textPlaceholder}>
+          <TextPlaceholder size="medium" />
+        </div>
+      ) : (
+        caption && (
+          <Text lineClamp={2} size="small">
+            {caption}
+          </Text>
+        )
+      )}
+    </>
+  );
+};
+
+// Renders a single image post preview
+const ImagePreview = ({
+  previewMedia,
+}: {
+  previewMedia: PreviewMedia[] | undefined;
+}) => {
+  const isLoading = !previewMedia;
+  const media = previewMedia?.find((media) => media.mediaSlotId === "media");
+  const fullWidth = (media?.previews.length ?? 1) * IMAGE_WIDTH;
+
+  return (
+    <Box borderRadius="large" className={styles.imageContainer}>
+      {isLoading || !media?.previews.length ? (
+        <div className={styles.imagePlaceholder}>
+          <Placeholder shape="rectangle" />
+        </div>
+      ) : (
+        <div className={styles.imageRow} style={{ width: fullWidth }}>
+          {media?.previews.map((p) => {
+            return (
+              <div key={p.id} className={styles.image}>
+                <PreviewRenderer preview={p} />
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </Box>
+  );
+};
+
+// Renders individual preview based on its type and status
+const PreviewRenderer = ({ preview }: { preview: Preview }) => {
+  const intl = useIntl();
+  // Handle different preview states
+  if (preview.status === "loading") {
+    return (
+      <ImageStatusText
+        text={intl.formatMessage({
+          defaultMessage: "Loading...",
+          description: "Text displayed while the preview is loading",
+        })}
+      />
+    );
+  }
+
+  if (preview.status === "error") {
+    return (
+      <ImageStatusText
+        text={intl.formatMessage({
+          defaultMessage: "Error loading preview",
+          description:
+            "Text displayed when there is an error loading the preview",
+        })}
+      />
+    );
+  }
+
+  // Handle image previews (ready status)
+  if (isImagePreviewReady(preview)) {
+    return (
+      <ImageCard
+        alt={intl.formatMessage(
+          {
+            defaultMessage: "Image preview {previewId}",
+            description: "Alt text for image preview in the preview UI",
+          },
+          { previewId: preview.id },
+        )}
+        thumbnailUrl={preview.url}
+      />
+    );
+  }
+
+  // Fallback for unknown preview types
+  return (
+    <Box
+      width="full"
+      height="full"
+      padding="2u"
+      display="flex"
+      alignItems="center"
+      justifyContent="center"
+    >
+      <Text size="medium" tone="tertiary" alignment="center">
+        <FormattedMessage
+          defaultMessage="Preview not available"
+          description="Text displayed when the preview type is not supported"
+        />
+      </Text>
+    </Box>
+  );
+};
+
+// Helper component to display status text for loading/error states
+const ImageStatusText = ({ text }: { text: string }) => (
+  <Box
+    width="full"
+    height="full"
+    padding="2u"
+    display="flex"
+    alignItems="center"
+    justifyContent="center"
+  >
+    <Text size="medium" tone="tertiary" alignment="center">
+      {text}
+    </Text>
+  </Box>
+);
+
+/**
+ * Type guard to check if a preview is an image preview that's ready to display
+ */
+export function isImagePreviewReady(preview: Preview): preview is Preview & {
+  kind: "image";
+  status: "ready";
+  url: string;
+} {
+  return (
+    preview.kind === "image" &&
+    preview.status === "ready" &&
+    preview.url != null
+  );
+}

package/templates/content_publisher/src/intents/content_publisher/preview_ui.tsx

@@ -0,0 +1,53 @@
+import type { OutputType, PreviewMedia } from "@canva/intents/content";
+import { useEffect, useState } from "react";
+import * as styles from "../../../styles/preview_ui.css";
+import { PostPreview } from "./post_preview";
+import { parsePublishSettings } from "./types";
+
+interface PreviewUiProps {
+  registerOnPreviewChange: (
+    callback: (opts: {
+      previewMedia: PreviewMedia[];
+      outputType: OutputType;
+      publishRef?: string;
+    }) => void,
+  ) => () => void;
+}
+
+// TODO: Replace with real user data from your platform
+// After implementing authentication (see README), fetch the connected user's profile
+// to display their actual username and avatar in the preview.
+const username = "username";
+
+// Main preview UI component that receives preview updates when settings or pages change.
+// Preview UI is more flexible to align with your platform's design system, so it is not constrained to the Canva design system.
+export const PreviewUi = ({ registerOnPreviewChange }: PreviewUiProps) => {
+  const [previewData, setPreviewData] = useState<{
+    previewMedia: PreviewMedia[];
+    outputType: OutputType;
+    publishRef?: string;
+  } | null>(null);
+
+  // Register to receive preview updates whenever settings or pages change
+  useEffect(() => {
+    const dispose = registerOnPreviewChange((data) => {
+      setPreviewData(data);
+    });
+    return dispose;
+  }, [registerOnPreviewChange]);
+
+  const { previewMedia, publishRef, outputType } = previewData ?? {};
+  const publishSettings = parsePublishSettings(publishRef);
+
+  return (
+    <div className={styles.container}>
+      {outputType?.id === "post" && (
+        <PostPreview
+          previewMedia={previewMedia}
+          settings={publishSettings}
+          username={username}
+        />
+      )}
+    </div>
+  );
+};

package/templates/content_publisher/src/intents/content_publisher/settings_ui.tsx

@@ -0,0 +1,71 @@
+import { FormField, Rows, Text, TextInput } from "@canva/app-ui-kit";
+import type {
+  PublishRefValidityState,
+  RenderSettingsUiRequest,
+  SettingsUiContext,
+} from "@canva/intents/content";
+import { useEffect, useState } from "react";
+import { useIntl } from "react-intl";
+import * as styles from "styles/components.css";
+import type { PublishSettings } from "./types";
+
+// Settings UI component for configuring publish settings
+export const SettingsUi = ({
+  updatePublishSettings,
+  registerOnSettingsUiContextChange,
+}: RenderSettingsUiRequest) => {
+  const intl = useIntl();
+  const [settings, setSettings] = useState<PublishSettings>({ caption: "" });
+  const [settingsUiContext, setSettingsUiContext] =
+    useState<SettingsUiContext | null>(null);
+
+  // Listen for settings UI context changes (e.g., when output type changes)
+  useEffect(() => {
+    const dispose = registerOnSettingsUiContextChange((context) => {
+      setSettingsUiContext(context);
+    });
+    return dispose;
+  }, [registerOnSettingsUiContextChange]);
+
+  return (
+    <div className={styles.scrollContainer}>
+      <Rows spacing="2u">
+        {settingsUiContext?.outputType.displayName && (
+          <Text>{settingsUiContext?.outputType.displayName}</Text>
+        )}
+        <FormField
+          label={intl.formatMessage({
+            defaultMessage: "Caption",
+            description: "Label for the caption input field",
+          })}
+          control={(props) => (
+            <TextInput
+              {...props}
+              value={settings.caption}
+              onChange={(caption) => {
+                const updatedSettings = { ...settings, caption };
+                setSettings(updatedSettings);
+                updatePublishSettings({
+                  publishRef: JSON.stringify(settings),
+                  validityState: validatePublishRef(settings),
+                });
+              }}
+            />
+          )}
+        />
+      </Rows>
+    </div>
+  );
+};
+
+// Validates the publish settings to enable/disable the publish button
+// Returns "valid" when all required fields are filled
+const validatePublishRef = (
+  publishRef: PublishSettings,
+): PublishRefValidityState => {
+  // caption is required
+  if (publishRef.caption.length === 0) {
+    return "invalid_missing_required_fields";
+  }
+  return "valid";
+};