convex 1.34.1 → 1.35.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.34.1",
+  "version": "1.35.1",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -178,6 +178,7 @@
   "peerDependencies": {
     "@auth0/auth0-react": "^2.0.1",
     "@clerk/clerk-react": "^4.12.8 || ^5.0.0",
+    "@clerk/react": "^6.0.0",
     "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -189,6 +190,9 @@
     },
     "@clerk/clerk-react": {
       "optional": true
+    },
+    "@clerk/react": {
+      "optional": true
     }
   },
   "@comment devDependencies": [
@@ -199,11 +203,11 @@
     "@auth0/auth0-react": "2.11.0",
     "@babel/parser": "^7.27.1",
     "@babel/types": "^7.27.1",
-    "@clerk/clerk-react": "^5.20.0",
+    "@clerk/react": "^6.0.0",
     "@commander-js/extra-typings": "^14.0.0",
     "@convex-dev/platform": "0.1.6",
     "@eslint/compat": "~2.0.0",
-    "@eslint/eslintrc": "~3.3.0",
+    "@eslint/eslintrc": "^3",
     "@eslint/js": "~9.39.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@octokit/openapi-types": "~25.0.0",
@@ -229,7 +233,7 @@
     "bufferutil": "^4.0.7",
     "chalk": "5",
     "chokidar": "3.6.0",
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "deep-equal": "2.2.3",
     "depcheck": "~1.4.7",
     "detect-port": "^2.1.0",
@@ -244,10 +248,10 @@
     "fetch-retry": "~6.0.0",
     "find-up": "^8.0.0",
     "globals": "~17.0.0",
-    "happy-dom": "~20.6.0",
+    "happy-dom": "~20.8.0",
     "jsdom": "~27.4.0",
     "json5": "~2.2.3",
-    "knip": "~5.79.0",
+    "knip": "~5.86.0",
     "napi-wasm": "1.1.3",
     "open": "^8.3.0",
     "openapi-fetch": "~0.15.0",
@@ -262,7 +266,7 @@
     "serve-handler": "~6.1.6",
     "shx": "~0.4.0",
     "skott": "~0.35.4",
-    "tar": "^7.5.10",
+    "tar": "^7.5.11",
     "tsx": "^4.19.4",
     "typedoc": "^0.24.6",
     "typescript": "~5.0.3",

package/schemas/convex.schema.json

@@ -150,8 +150,8 @@
         },
         "legacyComponentApi": {
           "type": "boolean",
-          "description": "When true (or omitted, default is true), generates inline expanded types for component APIs. When false, generates import-based component API references instead. The import-based format is more modern and recommended for projects using components.\n\nNote: When false, component.ts files are automatically generated for each component.",
-          "default": true
+          "description": "When true, generates inline expanded types for component APIs. When false (recommended), generates import-based component API references instead.",
+          "default": false
         },
         "staticApi": {
           "type": "boolean",
@@ -199,6 +199,19 @@
           "description": "Deprecated. Use `enabled` instead.",
           "deprecated": true,
           "default": false
+        },
+        "skills": {
+          "type": "object",
+          "description": "Configuration for agent skills installed by Convex.",
+          "properties": {
+            "agents": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "List of agents to install skills for (e.g. 'claude-code', 'codex', 'cursor'). Defaults to ['claude-code', 'codex']. For a list of supported agents see: https://github.com/vercel-labs/skills?tab=readme-ov-file#supported-agents",
+              "default": ["claude-code", "codex"]
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/src/cli/aiFiles.ts

@@ -1,22 +1,26 @@
 import path from "path";
 import { Command } from "@commander-js/extra-typings";
+import { chalkStderr } from "chalk";
+import { logMessage } from "../bundler/log.js";
 import { oneoffContext } from "../bundler/context.js";
 import { readProjectConfig } from "./lib/config.js";
 import { functionsDir } from "./lib/utils/utils.js";
 import {
   installAiFiles,
   enableAiFiles,
+  disableAiFiles,
   removeAiFiles,
-  safelyAttemptToDisableAiFiles,
 } from "./lib/aiFiles/index.js";
 import { statusAiFiles } from "./lib/aiFiles/status.js";
+import { writeAiFilesConfig } from "./lib/config.js";
 
 async function resolveProjectPaths() {
   const ctx = await oneoffContext({});
   const { configPath, projectConfig } = await readProjectConfig(ctx);
   const convexDir = path.resolve(functionsDir(configPath, projectConfig));
   const projectDir = path.resolve(path.dirname(configPath));
-  return { projectDir, convexDir };
+  const aiFilesConfig = projectConfig.aiFiles;
+  return { projectDir, convexDir, aiFilesConfig, projectConfig };
 }
 
 const aiInstall = new Command("install")
@@ -26,12 +30,15 @@ const aiInstall = new Command("install")
       "  - convex/_generated/ai/guidelines.md\n" +
       "  - AGENTS.md (Convex section only)\n" +
       "  - CLAUDE.md (Convex section only)\n" +
-      "  - Agent skills (installed to each coding agent's native path)",
+      "  - Agent skills (installed to each coding agent's native path, configured via convex.json)",
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir } = await resolveProjectPaths();
-    await installAiFiles({ projectDir, convexDir });
+    const { projectDir, convexDir, aiFilesConfig } =
+      await resolveProjectPaths();
+    await installAiFiles({ projectDir, convexDir, aiFilesConfig });
+
+    logMessage(`${chalkStderr.green("✔")} Convex AI files installed.`);
   });
 
 const aiEnable = new Command("enable")
@@ -42,8 +49,16 @@ const aiEnable = new Command("enable")
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir } = await resolveProjectPaths();
-    await enableAiFiles({ projectDir, convexDir });
+    const { projectDir, convexDir, aiFilesConfig } =
+      await resolveProjectPaths();
+
+    const newAiFilesConfig = await enableAiFiles({
+      projectDir,
+      convexDir,
+      aiFilesConfig,
+    });
+
+    await writeAiFilesConfig({ projectDir, aiFiles: newAiFilesConfig });
   });
 
 const aiUpdate = new Command("update")
@@ -53,12 +68,15 @@ const aiUpdate = new Command("update")
       "  - convex/_generated/ai/guidelines.md\n" +
       "  - AGENTS.md (Convex section only)\n" +
       "  - CLAUDE.md (Convex section only)\n" +
-      "  - Agent skills (installed to each coding agent's native path)\n\n",
+      "  - Agent skills (installed to each coding agent's native path, configured via convex.json)\n\n",
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir } = await resolveProjectPaths();
-    await installAiFiles({ projectDir, convexDir });
+    const { projectDir, convexDir, aiFilesConfig } =
+      await resolveProjectPaths();
+    await installAiFiles({ projectDir, convexDir, aiFilesConfig });
+
+    logMessage(`${chalkStderr.green("✔")} Convex AI files updated.`);
   });
 
 const aiDisable = new Command("disable")
@@ -72,8 +90,18 @@ const aiDisable = new Command("disable")
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir } = await resolveProjectPaths();
-    await safelyAttemptToDisableAiFiles(projectDir);
+    const { projectDir, aiFilesConfig } = await resolveProjectPaths();
+
+    const newAiFilesConfig = disableAiFiles(aiFilesConfig);
+
+    await writeAiFilesConfig({
+      projectDir,
+      aiFiles: newAiFilesConfig,
+    });
+
+    logMessage(
+      `${chalkStderr.green(`✔`)} Convex AI files disabled. Run ${chalkStderr.bold(`npx convex ai-files enable`)} to re-enable.`,
+    );
   });
 
 const aiStatus = new Command("status")
@@ -90,8 +118,10 @@ const aiStatus = new Command("status")
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir } = await resolveProjectPaths();
-    await statusAiFiles({ projectDir, convexDir });
+    const { projectDir, convexDir, aiFilesConfig } =
+      await resolveProjectPaths();
+
+    await statusAiFiles({ projectDir, convexDir, aiFilesConfig });
   });
 
 const aiRemove = new Command("remove")

package/src/cli/configure.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { updateEnvAndConfigForDeploymentSelection } from "./configure.js";
+import { writeDeploymentEnvVar } from "./lib/deployment.js";
+import { finalizeConfiguration } from "./lib/init.js";
+
+vi.mock("./lib/deployment.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./lib/deployment.js")>();
+  return {
+    ...actual,
+    writeDeploymentEnvVar: vi.fn().mockResolvedValue({
+      wroteToGitIgnore: false,
+      changedDeploymentEnvVar: true,
+    }),
+  };
+});
+
+vi.mock("./lib/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./lib/config.js")>();
+  return {
+    ...actual,
+    readProjectConfig: vi.fn().mockResolvedValue({
+      configPath: "convex.json",
+      projectConfig: { functions: "convex" },
+    }),
+    writeProjectConfig: vi.fn().mockResolvedValue(undefined),
+    ensureConvexFunctionsDir: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+vi.mock("./lib/init.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./lib/init.js")>();
+  return {
+    ...actual,
+    finalizeConfiguration: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+const ctx = {} as any;
+
+describe("updateEnvAndConfigForDeploymentSelection", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("prod deployments update CONVEX_URL and CONVEX_SITE_URL but not CONVEX_DEPLOYMENT", async () => {
+    await updateEnvAndConfigForDeploymentSelection(
+      ctx,
+      {
+        url: "https://happy-animal-123.convex.cloud",
+        siteUrl: "https://happy-animal-123.convex.site",
+        deploymentName: "happy-animal-123",
+        teamSlug: "my-team",
+        projectSlug: "my-project",
+        deploymentType: "prod",
+      },
+      null,
+    );
+
+    expect(writeDeploymentEnvVar).not.toHaveBeenCalled();
+    expect(finalizeConfiguration).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        changedDeploymentEnvVar: false,
+        wroteToGitIgnore: false,
+        url: "https://happy-animal-123.convex.cloud",
+        siteUrl: "https://happy-animal-123.convex.site",
+      }),
+    );
+  });
+
+  it("dev deployments update CONVEX_DEPLOYMENT, CONVEX_URL, and CONVEX_SITE_URL", async () => {
+    await updateEnvAndConfigForDeploymentSelection(
+      ctx,
+      {
+        url: "https://joyful-capybara-456.convex.cloud",
+        siteUrl: "https://joyful-capybara-456.convex.site",
+        deploymentName: "joyful-capybara-456",
+        teamSlug: "my-team",
+        projectSlug: "my-project",
+        deploymentType: "dev",
+      },
+      null,
+    );
+
+    expect(writeDeploymentEnvVar).toHaveBeenCalledWith(
+      ctx,
+      "dev",
+      {
+        team: "my-team",
+        project: "my-project",
+        deploymentName: "joyful-capybara-456",
+      },
+      null,
+    );
+    expect(finalizeConfiguration).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        changedDeploymentEnvVar: true,
+        url: "https://joyful-capybara-456.convex.cloud",
+        siteUrl: "https://joyful-capybara-456.convex.site",
+      }),
+    );
+  });
+
+  it("local deployments update CONVEX_DEPLOYMENT, CONVEX_URL, and CONVEX_SITE_URL", async () => {
+    await updateEnvAndConfigForDeploymentSelection(
+      ctx,
+      {
+        url: "https://swift-squirrel-789.convex.cloud",
+        siteUrl: "https://swift-squirrel-789.convex.site",
+        deploymentName: "swift-squirrel-789",
+        teamSlug: "my-team",
+        projectSlug: "my-project",
+        deploymentType: "local",
+      },
+      "existing-deployment-name",
+    );
+
+    expect(writeDeploymentEnvVar).toHaveBeenCalledWith(
+      ctx,
+      "local",
+      {
+        team: "my-team",
+        project: "my-project",
+        deploymentName: "swift-squirrel-789",
+      },
+      "existing-deployment-name",
+    );
+    expect(finalizeConfiguration).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        changedDeploymentEnvVar: true,
+        url: "https://swift-squirrel-789.convex.cloud",
+        siteUrl: "https://swift-squirrel-789.convex.site",
+      }),
+    );
+  });
+});

package/src/cli/configure.ts

@@ -16,7 +16,7 @@ import {
   checkAccessToSelectedProject,
   DeploymentSelectionWithinProject,
 } from "./lib/api.js";
-import { readProjectConfig, writeProjectConfig } from "./lib/config.js";
+import { readProjectConfig, ensureConvexFunctionsDir } from "./lib/config.js";
 import {
   DeploymentDetails,
   eraseDeploymentEnvVar,
@@ -44,7 +44,7 @@ import {
   promptYesNo,
 } from "./lib/utils/prompts.js";
 import { readGlobalConfig } from "./lib/utils/globalConfig.js";
-import { maybeSetupAiFiles } from "./lib/aiFiles/index.js";
+import { attemptSetupAiFiles } from "./lib/aiFiles/index.js";
 import {
   DeploymentSelection,
   deploymentNameFromSelection,
@@ -52,7 +52,7 @@ import {
 } from "./lib/deploymentSelection.js";
 import { ensureLoggedIn } from "./lib/login.js";
 import { handleAnonymousDeployment } from "./lib/localDeployment/anonymous.js";
-import { fetchDeploymentCanonicalSiteUrl } from "./lib/env.js";
+import { fetchDeploymentCanonicalUrls } from "./lib/deploy2.js";
 type DeploymentCredentials = {
   url: string;
   adminKey: string;
@@ -122,7 +122,7 @@ export async function deploymentCredentialsOrConfigure(
     chosenConfiguration,
     cmdOptions,
   );
-  const siteUrl = await fetchDeploymentCanonicalSiteUrl(ctx, {
+  const { convexSiteUrl: siteUrl } = await fetchDeploymentCanonicalUrls(ctx, {
     adminKey: selectedDeployment.adminKey,
     deploymentUrl: selectedDeployment.url,
   });
@@ -230,6 +230,7 @@ export async function _deploymentCredentialsOrConfigure(
       const isAgentMode = process.env.CONVEX_AGENT_MODE === "anonymous";
       if (
         !isAgentMode &&
+        process.stdin.isTTY &&
         hasAuth &&
         deploymentSelection.deploymentName !== null
       ) {
@@ -238,22 +239,17 @@ export async function _deploymentCredentialsOrConfigure(
           (await promptYesNo(ctx, {
             message: `${CONVEX_DEPLOYMENT_ENV_VAR_NAME} is configured with deployment ${deploymentSelection.deploymentName}, which is not linked with your account. Would you like to link it now?`,
           }));
-        if (!shouldConfigure) {
-          return await ctx.crash({
-            exitCode: 0,
-            errorType: "fatal",
-            printedMessage: `Run \`npx convex login --link-deployments\` first to link this deployment to your account, and then run \`npx convex dev\` again.`,
-          });
+        if (shouldConfigure) {
+          return await handleChooseProject(
+            ctx,
+            chosenConfiguration,
+            deploymentSelection.selectionWithinProject,
+            {
+              globallyForceCloud,
+            },
+            cmdOptions,
+          );
         }
-        return await handleChooseProject(
-          ctx,
-          chosenConfiguration,
-          deploymentSelection.selectionWithinProject,
-          {
-            globallyForceCloud,
-          },
-          cmdOptions,
-        );
       }
       const alreadyHasConfiguredAnonymousDeployment =
         deploymentSelection.deploymentName !== null &&
@@ -266,22 +262,23 @@ export async function _deploymentCredentialsOrConfigure(
         );
       }
 
-      const shouldPromptForLogin = isAgentMode
-        ? "no"
-        : alreadyHasConfiguredAnonymousDeployment
+      const shouldPromptForLogin =
+        isAgentMode || !process.stdin.isTTY
           ? "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",
-            });
+          : alreadyHasConfiguredAnonymousDeployment
+            ? "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 handleAnonymousDeployment(ctx, {
           chosenConfiguration,
@@ -625,8 +622,9 @@ async function selectNewProject(
   await doInitConvexFolder(ctx);
   const { configPath, projectConfig } = await readProjectConfig(ctx);
   const folder = functionsDir(configPath, projectConfig);
-  await maybeSetupAiFiles({
+  await attemptSetupAiFiles({
     ctx,
+    aiFilesConfig: projectConfig.aiFiles,
     convexDir: path.resolve(folder),
     projectDir: path.resolve(path.dirname(configPath)),
   });
@@ -685,8 +683,9 @@ async function selectExistingProject(
 
   const { configPath, projectConfig } = await readProjectConfig(ctx);
   const folder = functionsDir(configPath, projectConfig);
-  await maybeSetupAiFiles({
+  await attemptSetupAiFiles({
     ctx,
+    aiFilesConfig: projectConfig.aiFiles,
     convexDir: path.resolve(folder),
     projectDir: path.resolve(path.dirname(configPath)),
   });
@@ -787,17 +786,19 @@ export async function updateEnvAndConfigForDeploymentSelection(
   const { configPath, projectConfig } = await readProjectConfig(ctx);
 
   const { wroteToGitIgnore, changedDeploymentEnvVar } =
-    await writeDeploymentEnvVar(
-      ctx,
-      options.deploymentType,
-      {
-        team: options.teamSlug,
-        project: options.projectSlug,
-        deploymentName: options.deploymentName,
-      },
-      existingValue,
-    );
-  await writeProjectConfig(ctx, projectConfig);
+    options.deploymentType !== "prod"
+      ? await writeDeploymentEnvVar(
+          ctx,
+          options.deploymentType,
+          {
+            team: options.teamSlug,
+            project: options.projectSlug,
+            deploymentName: options.deploymentName,
+          },
+          existingValue,
+        )
+      : { wroteToGitIgnore: false, changedDeploymentEnvVar: false };
+  await ensureConvexFunctionsDir(ctx, projectConfig);
   await finalizeConfiguration(ctx, {
     deploymentType: options.deploymentType,
     deploymentName: options.deploymentName,

package/src/cli/deploy.ts

@@ -21,9 +21,12 @@ import { getTeamAndProjectFromPreviewAdminKey } from "./lib/deployment.js";
 import { runPush } from "./lib/components.js";
 import { promptYesNo } from "./lib/utils/prompts.js";
 import { deployToDeployment, runCommand } from "./lib/deploy2.js";
-import { getDeploymentSelection } from "./lib/deploymentSelection.js";
+import {
+  DeploymentSelection,
+  getDeploymentSelection,
+} from "./lib/deploymentSelection.js";
 import { deploymentNameAndTypeFromSelection } from "./lib/deploymentSelection.js";
-import { checkVersion } from "./lib/updates.js";
+import { checkVersionAndAiFilesStaleness } from "./lib/updates.js";
 import { readProjectConfig, getAuthKitConfig } from "./lib/config.js";
 import { ensureAuthKitProvisionedBeforeBuild } from "./lib/workos/workos.js";
 import { DASHBOARD_HOST } from "./lib/dashboard.js";
@@ -46,7 +49,7 @@ export const deploy = new Command("deploy")
   .addOption(
     new Option(
       "--preview-create <name>",
-      "The name to associate with this deployment if deploying to a newly created preview deployment. Defaults to the current Git branch name in Vercel, Netlify and GitHub CI. This parameter can only be used with a preview deploy key (when used with another type of key, the command will return an error).",
+      "The name to associate with this deployment if deploying to a newly created preview deployment. Defaults to the current Git branch name in Vercel, Netlify, Cloudflare Pages and GitHub CI. This parameter can only be used with a preview deploy key (when used with another type of key, the command will return an error).",
     ).conflicts("preview-name"),
   )
   .addOption(
@@ -93,7 +96,10 @@ Same format as .env.local or .env files, and overrides them.`,
   .action(async (cmdOptions) => {
     const ctx = await oneoffContext(cmdOptions);
 
-    const deploymentSelection = await getDeploymentSelection(ctx, cmdOptions);
+    const deploymentSelection = await getDeploymentSelection(ctx, {
+      ...cmdOptions,
+      implicitProd: true,
+    });
     if (
       cmdOptions.checkBuildEnvironment === "enable" &&
       isNonProdBuildEnvironment() &&
@@ -171,7 +177,7 @@ Same format as .env.local or .env files, and overrides them.`,
         });
       }
 
-      await deployToExistingDeployment(ctx, {
+      await deployToExistingDeployment(ctx, deploymentSelection, {
         ...cmdOptions,
         skipWorkosCheck: cmdOptions.skipWorkosCheck ?? false,
         allowDeletingLargeIndexes:
@@ -309,6 +315,7 @@ async function deployToNewPreviewDeployment(
 
 async function deployToExistingDeployment(
   ctx: Context,
+  deploymentSelection: DeploymentSelection,
   options: {
     verbose?: boolean | undefined;
     dryRun?: boolean | undefined;
@@ -331,10 +338,6 @@ async function deployToExistingDeployment(
     allowDeletingLargeIndexes: boolean;
   },
 ) {
-  const deploymentSelection = await getDeploymentSelection(ctx, {
-    ...options,
-    implicitProd: true,
-  });
   const deploymentToActOn = await loadSelectedDeploymentCredentials(
     ctx,
     deploymentSelection,
@@ -383,7 +386,7 @@ async function deployToExistingDeployment(
     ...(isCloudDeployment
       ? [
           usageStateWarning(ctx, deploymentFields.deploymentName),
-          checkVersion(ctx),
+          checkVersionAndAiFilesStaleness(ctx),
         ]
       : []),
   ]);