@canva/cli 1.13.0 → 1.15.0

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

@@ -0,0 +1,223 @@
+/* eslint-disable no-console */
+import { generatePreviewUrl } from "@canva/cli";
+import ngrok from "@ngrok/ngrok";
+import chalk from "chalk";
+import Table from "cli-table3";
+import nodemon from "nodemon";
+import open from "open";
+import os from "os";
+import webpack from "webpack";
+import WebpackDevServer from "webpack-dev-server";
+import { buildConfig } from "../../webpack.config";
+import type { Certificate } from "../ssl/ssl";
+import { createOrRetrieveCertificate } from "../ssl/ssl";
+import type { Context } from "./context";
+
+export const infoChalk = chalk.blue.bold;
+export const warnChalk = chalk.bgYellow.bold;
+export const errorChalk = chalk.bgRed.bold;
+export const highlightChalk = chalk.greenBright.bold;
+export const linkChalk = chalk.cyan;
+
+/**
+ * Returns the appropriate modifier key text based on the user's operating system.
+ * @returns "cmd" for macOS, "ctrl" for Windows and Linux
+ */
+export function getModifierKey(): string {
+  const platform = os.platform();
+  switch (platform) {
+    case "darwin": // macOS
+      return "cmd";
+    case "win32": // Windows
+      return "ctrl";
+    default: // Linux and others
+      return "ctrl";
+  }
+}
+
+export class AppRunner {
+  async run(ctx: Context) {
+    console.log(
+      infoChalk("Info:"),
+      `Starting development server for ${highlightChalk(ctx.entryDir)}\n`,
+    );
+
+    if (!ctx.hmrEnabled) {
+      console.log(
+        `${infoChalk(
+          "Note:",
+        )} Hot Module Replacement (HMR) not enabled. To enable it, please refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )}\n`,
+      );
+    }
+
+    let cert: Certificate | undefined;
+    if (ctx.httpsEnabled) {
+      try {
+        cert = await createOrRetrieveCertificate();
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          "Unable to generate SSL certificate.",
+        );
+        throw err;
+      }
+    }
+
+    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(
+      `${infoChalk(
+        "Note:",
+      )} For instructions on how to set up the app via the Developer Portal, see the ${highlightChalk(
+        "README.md",
+      )}.\n`,
+    );
+  }
+
+  private readonly maybeRunBackendServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+    webpackDevServer: WebpackDevServer,
+  ) => {
+    if (!ctx.developerBackendEntryPath) {
+      return;
+    }
+
+    // App ID must be set when running a backend example
+    if (!ctx.appId) {
+      console.log(
+        errorChalk("Error:"),
+        `'CANVA_APP_ID' environment variable is undefined. Refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )} on starting a backend example.`,
+      );
+      throw new Error("'CANVA_APP_ID' env variable not set.");
+    }
+
+    await new Promise((resolve) => {
+      const nodemonServer = nodemon({
+        script: ctx.developerBackendEntryPath,
+        ext: "ts",
+        env: {
+          SHOULD_ENABLE_HTTPS: ctx.httpsEnabled,
+          HTTPS_CERT_FILE: cert?.certFile || "",
+          HTTPS_KEY_FILE: cert?.keyFile || "",
+        },
+      });
+
+      nodemonServer.on("start", resolve);
+
+      nodemonServer.on("crash", async () => {
+        console.log(errorChalk("Shutting down local server.\n"));
+
+        await webpackDevServer.stop();
+        process.exit(1);
+      });
+    });
+
+    if (ctx.ngrokEnabled) {
+      console.log(
+        warnChalk("Warning:"),
+        `ngrok exposes a local port via a public URL. Be mindful of what's exposed and shut down the server when it's not in use.\n`,
+      );
+    }
+
+    let url = ctx.backendUrl;
+    if (ctx.ngrokEnabled) {
+      try {
+        const ngrokListener = await ngrok.forward({
+          addr: ctx.backendPort,
+          // requires an `NGROK_AUTHTOKEN` env var to be set
+          authtoken_from_env: true,
+        });
+        url = ngrokListener.url() ?? url;
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          `Unable to start ngrok server: ${err}`,
+        );
+      }
+    }
+
+    table.push(["Base URL (Backend)", linkChalk(url)]);
+  };
+
+  private readonly runWebpackDevServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+  ): Promise<WebpackDevServer> => {
+    const runtimeWebpackConfig = buildConfig({
+      appEntry: ctx.frontendEntryPath,
+      backendHost: ctx.backendHost,
+      devConfig: {
+        port: ctx.frontendPort,
+        enableHmr: ctx.hmrEnabled,
+        appId: ctx.appId,
+        appOrigin: ctx.appOrigin,
+        enableHttps: ctx.httpsEnabled,
+        ...cert,
+      },
+    });
+
+    const compiler = webpack(runtimeWebpackConfig);
+    const server = new WebpackDevServer(
+      runtimeWebpackConfig.devServer,
+      compiler,
+    );
+    await server.start();
+
+    table.push(["Development URL (Frontend)", linkChalk(ctx.frontendUrl)]);
+
+    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;
+    }
+
+    const modifierKey = getModifierKey();
+
+    table.push([
+      previewCellHeader,
+      {
+        content: `Preview URL (${modifierKey} + click)`,
+        href: generatePreviewResult.data,
+      },
+    ]);
+
+    if (openPreview) {
+      open(generatePreviewResult.data);
+    }
+  };
+}

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;