convex 1.34.1 → 1.35.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.34.1",
+  "version": "1.35.0",
   "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/browser/index.ts

@@ -40,3 +40,6 @@ export type { QueryJournal } from "./sync/protocol.js";
 /** @internal */
 export type { UserIdentityAttributes } from "./sync/protocol.js";
 export type { FunctionResult } from "./sync/function_result.js";
+/** @internal */
+export { convexQueryOptions } from "./query_options.js";
+export type { QueryOptions } from "./query_options.js";

package/src/browser/query_options.test.ts

@@ -1,7 +1,6 @@
 import { test } from "vitest";
 import { makeFunctionReference } from "../server/index.js";
 import { EmptyObject } from "../server/registration.js";
-import { ConvexReactClient } from "../react/client.js";
 import { convexQueryOptions } from "./query_options.js";
 
 const apiQueryFuncWithArgs = makeFunctionReference<
@@ -42,11 +41,3 @@ test("convexQueryOptions", async () => {
     args: { name: "hey" },
   });
 });
-
-test("prewarmQuery types", async () => {
-  const client = {
-    prewarmQuery: () => {},
-  } as unknown as ConvexReactClient;
-
-  client.prewarmQuery({ query: apiQueryFuncWithArgs, args: { name: "hi" } });
-});

package/src/browser/query_options.ts

@@ -1,26 +1,47 @@
-/**
- * Query options are a potential new API for a variety of functions, but in particular a new overload of the React hook for queries.
- *
- * Inspired by https://tanstack.com/query/v5/docs/framework/react/guides/query-options
- */
+// Inspired by https://tanstack.com/query/v5/docs/framework/react/guides/query-options
 import type { FunctionArgs, FunctionReference } from "../server/api.js";
 
-// TODO if this type can encompass all use cases we can add not requiring args for queries
-// that don't take arguments. Goal would be that queryOptions allows leaving out args,
-// but queryOptions returns an object that always contains args. Helpers, "middleware,"
-// anything that intercepts these arguments
 /**
- * Query options.
+ * Options for a Convex query: the query function reference and its arguments.
+ *
+ * Used with the object-form overload of {@link useQuery}.
+ *
+ * @public
  */
-export type ConvexQueryOptions<Query extends FunctionReference<"query">> = {
+export type QueryOptions<Query extends FunctionReference<"query">> = {
+  /**
+   * The query function to run.
+   */
   query: Query;
+  /**
+   * The arguments to the query function.
+   */
   args: FunctionArgs<Query>;
-  extendSubscriptionFor?: number;
 };
 
-// This helper helps more once we have more inference happening.
+/**
+ * Creates a type-safe {@link QueryOptions} object for a Convex query.
+ *
+ * This is an identity function that exists to provide type inference — passing
+ * your query and args through this helper ensures TypeScript infers the correct
+ * `Query` type parameter, which enables precise return types on hooks like
+ * {@link useQuery}.
+ *
+ * ```typescript
+ * const opts = convexQueryOptions({
+ *   query: api.users.getById,
+ *   args: { id: userId },
+ * });
+ * // opts is typed as QueryOptions<typeof api.users.getById>
+ * client.prewarmQuery(opts);
+ * ```
+ *
+ * @param options - The query and its arguments.
+ * @returns The same object, typed as `QueryOptions<Query>`.
+ * @internal
+ */
 export function convexQueryOptions<Query extends FunctionReference<"query">>(
-  options: ConvexQueryOptions<Query>,
-): ConvexQueryOptions<Query> {
+  options: QueryOptions<Query>,
+): QueryOptions<Query> {
   return options;
 }

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/codegen_templates/readme.ts

@@ -37,7 +37,20 @@ export const myQueryFunction = query({
 Using this query function in a React component looks like:
 
 \`\`\`ts
-const data = useQuery(api.myFunctions.myQueryFunction, { first: 10, second: "hello" });
+const state = useQuery({
+  query: api.myFunctions.myQueryFunction,
+  args: { first: 10, second: "hello" },
+});
+
+if (state.status === "pending") {
+  return <div>Loading...</div>;
+}
+
+if (state.status === "error") {
+  return <div>Error: {state.error.message}</div>;
+}
+
+const data = state.data;
 \`\`\`
 
 

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,