Update messaging in CLI for initial flow (#35961)

The main change is adding a prompt on first use for whether to start without an account (default) or to create an account. It's gated behind the `CONVEX_TRY_IT_OUT` env var.

I also printed a link to the dashboard in one of the first messages in the dev loop (moved around code to make that happen).

Also made it so that the anonymous / self-hosted dashboard can accept a hint for the deployment name to select as a query param

GitOrigin-RevId: 2382d48deb29ae2c08f3216483f3bdc290ab859b

Author: sshader

npm-packages/convex/src/cli/configure.ts

@@ -41,7 +41,7 @@ import {
 } from "./lib/utils/utils.js";
 import { writeConvexUrlToEnvFile } from "./lib/envvars.js";
 import path from "path";
-import { projectDashboardUrl } from "./dashboard.js";
+import { projectDashboardUrl } from "./lib/dashboard.js";
 import { doCodegen, doInitCodegen } from "./lib/codegen.js";
 import { handleLocalDeployment } from "./lib/localDeployment/localDeployment.js";
 import {
@@ -54,6 +54,7 @@ import {
   DeploymentSelection,
   ProjectSelection,
   deploymentNameFromSelection,
+  shouldAllowTryItOut,
 } from "./lib/deploymentSelection.js";
 import { ensureLoggedIn } from "./lib/login.js";
 import { handleTryItOutDeployment } from "./lib/localDeployment/tryitout.js";
@@ -260,21 +261,47 @@ export async function _deploymentCredentialsOrConfigure(
           cmdOptions,
         );
       }
-      const result = await handleTryItOutDeployment(ctx, {
+      const shouldPromptForLogin =
+        deploymentSelection.deploymentName !== null
+          ? "no"
+          : await promptOptions(ctx, {
+              message:
+                "Welcome to Convex! Would you like to login to your account?",
+              choices: [
+                {
+                  name: "Start without an account (run Convex locally)",
+                  value: "no",
+                },
+                { name: "Login or create an account", value: "yes" },
+              ],
+              default: "no",
+            });
+      if (shouldPromptForLogin === "no") {
+        const result = await handleTryItOutDeployment(ctx, {
+          chosenConfiguration,
+          deploymentName: deploymentSelection.deploymentName,
+          ...cmdOptions.localOptions,
+        });
+        return {
+          adminKey: result.adminKey,
+          url: result.deploymentUrl,
+          deploymentFields: {
+            deploymentName: result.deploymentName,
+            deploymentType: "tryitout",
+            projectSlug: null,
+            teamSlug: null,
+          },
+        };
+      }
+      return await handleChooseProject(
+        ctx,
         chosenConfiguration,
-        deploymentName: deploymentSelection.deploymentName,
-        ...cmdOptions.localOptions,
-      });
-      return {
-        adminKey: result.adminKey,
-        url: result.deploymentUrl,
-        deploymentFields: {
-          deploymentName: result.deploymentName,
-          deploymentType: "tryitout",
-          projectSlug: null,
-          teamSlug: null,
+        {
+          globallyForceCloud,
+          partitionId,
         },
-      };
+        cmdOptions,
+      );
     }
   }
 }
@@ -296,9 +323,10 @@ async function handleDeploymentWithinProject(
   },
 ) {
   const hasAuth = ctx.bigBrainAuth() !== null;
-  const loginMessage = hasAuth
-    ? undefined
-    : `Tip: You can try out Convex without creating an account by clearing the ${CONVEX_DEPLOYMENT_ENV_VAR_NAME} environment variable.`;
+  const loginMessage =
+    hasAuth && shouldAllowTryItOut()
+      ? undefined
+      : `Tip: You can try out Convex without creating an account by clearing the ${CONVEX_DEPLOYMENT_ENV_VAR_NAME} environment variable.`;
   await ensureLoggedIn(ctx, {
     message: loginMessage,
     overrideAuthUrl: cmdOptions.overrideAuthUrl,
@@ -753,6 +781,7 @@ export async function updateEnvAndConfigForDeploymentSelection(
   });
   await finalizeConfiguration(ctx, {
     deploymentType: options.deploymentType,
+    deploymentName: options.deploymentName,
     url: options.url,
     wroteToGitIgnore,
     changedDeploymentEnvVar,

npm-packages/convex/src/cli/convexExport.ts

@@ -6,7 +6,7 @@ import {
   deploymentSelectionWithinProjectFromOptions,
   loadSelectedDeploymentCredentials,
 } from "./lib/api.js";
-import { deploymentDashboardUrlPage } from "./dashboard.js";
+import { deploymentDashboardUrlPage } from "./lib/dashboard.js";
 import { actionDescription } from "./lib/command.js";
 import { exportFromDeployment } from "./lib/convexExport.js";
 import { getDeploymentSelection } from "./lib/deploymentSelection.js";

npm-packages/convex/src/cli/convexImport.ts

@@ -7,7 +7,7 @@ import {
 } from "./lib/api.js";
 import { Command } from "@commander-js/extra-typings";
 import { actionDescription } from "./lib/command.js";
-import { deploymentDashboardUrlPage } from "./dashboard.js";
+import { deploymentDashboardUrlPage } from "./lib/dashboard.js";
 import { importIntoDeployment } from "./lib/convexImport.js";
 import { getDeploymentSelection } from "./lib/deploymentSelection.js";
 

npm-packages/convex/src/cli/dashboard.ts

@@ -15,11 +15,8 @@ import {
 import { actionDescription } from "./lib/command.js";
 import { getDeploymentSelection } from "./lib/deploymentSelection.js";
 import { isTryItOutDeployment } from "./lib/deployment.js";
-import { loadDashboardConfig } from "./lib/localDeployment/filePaths.js";
-import {
-  DEFAULT_LOCAL_DASHBOARD_API_PORT,
-  checkIfDashboardIsRunning,
-} from "./lib/localDeployment/dashboard.js";
+import { checkIfDashboardIsRunning } from "./lib/localDeployment/dashboard.js";
+import { getDashboardUrl } from "./lib/dashboard.js";
 
 export const DASHBOARD_HOST = process.env.CONVEX_PROVISION_HOST
   ? "http://localhost:6789"
@@ -52,35 +49,23 @@ export const dashboard = new Command("dashboard")
       logMessage(ctx, chalk.yellow(msg));
       return;
     }
+    const dashboardUrl = getDashboardUrl(ctx, deployment.deploymentFields);
     if (isTryItOutDeployment(deployment.deploymentFields.deploymentName)) {
-      const dashboardConfig = loadDashboardConfig(ctx);
       const warningMessage = `You are not currently running the dashboard locally. Make sure \`npx convex dev\` is running and try again.`;
-      if (dashboardConfig === null) {
+      if (dashboardUrl === null) {
         logWarning(ctx, warningMessage);
         return;
       }
-      const isLocalDashboardRunning =
-        await checkIfDashboardIsRunning(dashboardConfig);
+      const isLocalDashboardRunning = await checkIfDashboardIsRunning(ctx);
       if (!isLocalDashboardRunning) {
         logWarning(ctx, warningMessage);
         return;
       }
-
-      const queryString =
-        dashboardConfig.apiPort !== DEFAULT_LOCAL_DASHBOARD_API_PORT
-          ? `?apiPort=${dashboardConfig.apiPort}`
-          : "";
-      const dashboardUrl = `http://127.0.0.1:${dashboardConfig.port}${queryString}`;
       await logOrOpenUrl(ctx, dashboardUrl, options.open);
       return;
     }
 
-    const loginUrl = deploymentDashboardUrlPage(
-      deployment.deploymentFields.deploymentName,
-      "",
-    );
-
-    await logOrOpenUrl(ctx, loginUrl, options.open);
+    await logOrOpenUrl(ctx, dashboardUrl ?? DASHBOARD_HOST, options.open);
   });
 
 async function logOrOpenUrl(ctx: Context, url: string, shouldOpen: boolean) {
@@ -91,26 +76,3 @@ async function logOrOpenUrl(ctx: Context, url: string, shouldOpen: boolean) {
     logOutput(ctx, url);
   }
 }
-
-export function deploymentDashboardUrlPage(
-  configuredDeployment: string | null,
-  page: string,
-): string {
-  return `${DASHBOARD_HOST}/d/${configuredDeployment}${page}`;
-}
-
-export function deploymentDashboardUrl(
-  team: string,
-  project: string,
-  deploymentName: string,
-) {
-  return `${projectDashboardUrl(team, project)}/${deploymentName}`;
-}
-
-export function projectDashboardUrl(team: string, project: string) {
-  return `${teamDashboardUrl(team)}/${project}`;
-}
-
-export function teamDashboardUrl(team: string) {
-  return `${DASHBOARD_HOST}/t/${team}`;
-}

npm-packages/convex/src/cli/lib/config.ts

@@ -19,7 +19,7 @@ import {
   entryPointsByEnvironment,
 } from "../../bundler/index.js";
 import { version } from "../version.js";
-import { deploymentDashboardUrlPage } from "../dashboard.js";
+import { deploymentDashboardUrlPage } from "./dashboard.js";
 import {
   formatSize,
   functionsDir,

npm-packages/convex/src/cli/lib/dashboard.ts

@@ -0,0 +1,56 @@
+import { Context } from "../../bundler/context.js";
+import { DeploymentType } from "./api.js";
+import { dashboardUrl as localDashboardUrl } from "./localDeployment/dashboard.js";
+
+export const DASHBOARD_HOST = process.env.CONVEX_PROVISION_HOST
+  ? "http://localhost:6789"
+  : "https://dashboard.convex.dev";
+
+export function getDashboardUrl(
+  ctx: Context,
+  {
+    deploymentName,
+    deploymentType,
+  }: {
+    deploymentName: string;
+    deploymentType: DeploymentType;
+  },
+): string | null {
+  switch (deploymentType) {
+    case "tryitout": {
+      return localDashboardUrl(ctx, deploymentName);
+    }
+    case "local":
+    case "dev":
+    case "prod":
+    case "preview":
+      return deploymentDashboardUrlPage(deploymentName, "");
+    default: {
+      const _exhaustiveCheck: never = deploymentType;
+      return _exhaustiveCheck;
+    }
+  }
+}
+
+export function deploymentDashboardUrlPage(
+  configuredDeployment: string | null,
+  page: string,
+): string {
+  return `${DASHBOARD_HOST}/d/${configuredDeployment}${page}`;
+}
+
+export function deploymentDashboardUrl(
+  team: string,
+  project: string,
+  deploymentName: string,
+) {
+  return `${projectDashboardUrl(team, project)}/${deploymentName}`;
+}
+
+export function projectDashboardUrl(team: string, project: string) {
+  return `${teamDashboardUrl(team)}/${project}`;
+}
+
+export function teamDashboardUrl(team: string) {
+  return `${DASHBOARD_HOST}/t/${team}`;
+}

npm-packages/convex/src/cli/lib/init.ts

@@ -2,12 +2,14 @@ import chalk from "chalk";
 import { Context, logFinishedStep, logMessage } from "../../bundler/context.js";
 import { DeploymentType } from "./api.js";
 import { writeConvexUrlToEnvFile } from "./envvars.js";
+import { getDashboardUrl } from "./dashboard.js";
 
 export async function finalizeConfiguration(
   ctx: Context,
   options: {
     functionsPath: string;
     deploymentType: DeploymentType;
+    deploymentName: string;
     url: string;
     wroteToGitIgnore: boolean;
     changedDeploymentEnvVar: boolean;
@@ -17,29 +19,57 @@ export async function finalizeConfiguration(
   if (envVarWrite !== null) {
     logFinishedStep(
       ctx,
-      `Provisioned a ${options.deploymentType} deployment and saved its:\n` +
+      `${messageForDeploymentType(options.deploymentType, options.url)} and saved its:\n` +
         `    name as CONVEX_DEPLOYMENT to .env.local\n` +
         `    URL as ${envVarWrite.envVar} to ${envVarWrite.envFile}`,
     );
   } else if (options.changedDeploymentEnvVar) {
     logFinishedStep(
       ctx,
-      `Provisioned ${options.deploymentType} deployment and saved its name as CONVEX_DEPLOYMENT to .env.local`,
+      `${messageForDeploymentType(options.deploymentType, options.url)} and saved its name as CONVEX_DEPLOYMENT to .env.local`,
     );
   }
   if (options.wroteToGitIgnore) {
     logMessage(ctx, chalk.gray(`  Added ".env.local" to .gitignore`));
   }
+  if (options.deploymentType === "tryitout") {
+    logMessage(
+      ctx,
+      `Run \`npx convex login\` at any time to create an account and link this deployment.`,
+    );
+  }
 
   const anyChanges =
     options.wroteToGitIgnore ||
     options.changedDeploymentEnvVar ||
     envVarWrite !== null;
   if (anyChanges) {
+    const dashboardUrl = getDashboardUrl(ctx, {
+      deploymentName: options.deploymentName,
+      deploymentType: options.deploymentType,
+    });
     logMessage(
       ctx,
       `\nWrite your Convex functions in ${chalk.bold(options.functionsPath)}\n` +
-        "Give us feedback at https://convex.dev/community or [email protected]\n",
+        "Give us feedback at https://convex.dev/community or [email protected]\n" +
+        `View the Convex dashboard at ${dashboardUrl}\n`,
     );
   }
 }
+
+function messageForDeploymentType(deploymentType: DeploymentType, url: string) {
+  switch (deploymentType) {
+    case "tryitout":
+      return `Started running a deployment locally at ${url}`;
+    case "local":
+      return `Started running a deployment locally at ${url}`;
+    case "dev":
+    case "prod":
+    case "preview":
+      return `Provisioned a ${deploymentType} deployment`;
+    default: {
+      const _exhaustiveCheck: never = deploymentType;
+      return `Provisioned a ${deploymentType as any} deployment`;
+    }
+  }
+}