convex 1.34.0 → 1.35.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.34.0",
+  "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",
@@ -189,10 +189,29 @@
       "type": "object",
       "description": "User-configurable settings for Convex AI files behavior.",
       "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "When false, disables all Convex AI files prompts and staleness messages in `npx convex dev`. Use `npx convex ai-files enable` to re-enable.",
+          "default": true
+        },
         "disableStalenessMessage": {
           "type": "boolean",
-          "description": "When true, suppresses Convex AI files install/staleness nags in `npx convex dev`.",
+          "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/browser/sync/authentication_manager.ts

@@ -174,6 +174,14 @@ export class AuthenticationManager {
       return;
     }
 
+    this._logVerbose(
+      `auth state is ${this.authState.state} when handling transition`,
+    );
+
+    // This transition advanced the auth version, which means the token used was valid
+    // and the client and server auth states are in sync.
+    this.syncState.markAuthCompletion();
+
     if (this.authState.state === "waitingForServerConfirmationOfCachedToken") {
       this._logVerbose("server confirmed auth token is valid");
       void this.refetchToken();
@@ -455,11 +463,8 @@ export class AuthenticationManager {
       }
     }
     if (this.authState.state === "waitingForScheduledRefetch") {
+      // TODO: this side-effect would be better situated with scheduling refetch
       clearTimeout(this.authState.refetchTokenTimeoutId);
-
-      // The waitingForScheduledRefetch state is the most quiesced authed state.
-      // Let the syncState know that auth is in a good state, so it can reset failure backoffs
-      this.syncState.markAuthCompletion();
     }
     this.authState = newAuth;
   }

package/src/browser/sync/client_node.test.ts

@@ -2,6 +2,7 @@ import child_process from "child_process";
 
 import { test, expect } from "vitest";
 import { Long } from "../../vendor/long.js";
+import { createHmac } from "crypto";
 
 import { BaseConvexClient } from "./client.js";
 import {
@@ -1026,3 +1027,127 @@ test("Backoff does not reset for idle client until server re-confirms queries",
     await client.close();
   });
 });
+
+// We had an issue where fixing a bug related to having the client do proper exponential backoff
+// resulted in revealing that if a client was authenticated and had a WebSocket disconnect, the
+// count of retries would never get reset upon reconnect. This test covers that scenario.
+test("Retries do not increase across connections for auth'd clients", async () => {
+  await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
+    const client = new BaseConvexClient(address, () => null, {
+      webSocketConstructor: nodeWebSocket,
+      unsavedChangesWarning: false,
+      logger: true,
+      verbose: true,
+    });
+
+    // Setup auth
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + 3600;
+    const token = encodeJwt({ sub: "user_123", exp, iat }, "test-secret");
+    client.setAuth(
+      async () => token,
+      (_) => {},
+    );
+
+    // Verify client handshake on "server" side.
+    expect((await receive()).type).toEqual("Connect");
+    expect((await receive()).type).toEqual("Authenticate");
+    expect((await receive()).type).toEqual("ModifyQuerySet");
+
+    // Respond to the handshake noting that the identity was accepted (increased version).
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 0, ts: Long.fromNumber(0) },
+      endVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      modifications: [],
+    });
+
+    // Subscribe to a query and verify the "server" receives it.
+    client.subscribe("queries:myQuery", {});
+    expect((await receive()).type).toEqual("ModifyQuerySet");
+
+    // Respond to the subscription with a result.
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      endVersion: { querySet: 1, identity: 1, ts: Long.fromNumber(200) },
+      modifications: [
+        {
+          type: "QueryUpdated",
+          queryId: 0,
+          value: "result",
+          logLines: [],
+          journal: null,
+        },
+      ],
+    });
+
+    // Verify the client gets the subscription result.
+    for (let i = 0; i < 20; i++) {
+      if (client.localQueryResult("queries:myQuery", {}) === "result") break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    expect(client.localQueryResult("queries:myQuery", {})).toEqual("result");
+
+    // Unceremoniously drop the connection.
+    close();
+
+    // The "server" should see the client handshake for a reconnect.
+    expect((await receive()).type).toEqual("Connect");
+    expect((await receive()).type).toEqual("Authenticate");
+    expect((await receive()).type).toEqual("ModifyQuerySet");
+
+    // The client should record that it has begun a retry.
+    expect(client.connectionState().connectionRetries).toBe(1);
+
+    // Respond to the handshake noting that the identity was accepted (increased version).
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 0, ts: Long.fromNumber(0) },
+      endVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      modifications: [],
+    });
+    // Let client handle the transition.
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Respond to the re-subscription with a result.
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      endVersion: { querySet: 1, identity: 1, ts: Long.fromNumber(200) },
+      modifications: [
+        {
+          type: "QueryUpdated",
+          queryId: 0,
+          value: "updated result",
+          logLines: [],
+          journal: null,
+        },
+      ],
+    });
+
+    for (let i = 0; i < 20; i++) {
+      if (client.localQueryResult("queries:myQuery", {}) === "updated result")
+        break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    // Verify the client gets the subscription result.
+    expect(client.localQueryResult("queries:myQuery", {})).toEqual(
+      "updated result",
+    );
+
+    // Client has resynced - should be at 0 retries
+    expect(client.connectionState().connectionRetries).toBe(0);
+  });
+});
+
+function encodeJwt(payload: object, secret: string): string {
+  const header = Buffer.from(
+    JSON.stringify({ alg: "HS256", typ: "JWT" }),
+  ).toString("base64url");
+  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const sig = createHmac("sha256", secret)
+    .update(`${header}.${body}`)
+    .digest("base64url");
+  return `${header}.${body}.${sig}`;
+}

package/src/browser/sync/web_socket_manager.ts

@@ -126,12 +126,6 @@ const serverDisconnectErrors = {
   VectorIndexesUnavailable: { timeout: 1000 },
   SearchIndexesUnavailable: { timeout: 1000 },
   TableSummariesUnavailable: { timeout: 1000 },
-  // ErrorMetadata::service_unavailable() when backend/conductor is unreachable
-  ServiceUnavailable: { timeout: 3000 },
-  // ErrorMetadata::rejected_before_execution() when funrun workers are unavailable
-  WorkerOverloaded: { timeout: 3000 },
-  IsolateNotClean: { timeout: 3000 },
-  InitialPermitTimeoutError: { timeout: 3000 },
   // More ErrorMetadata::overloaded()
   VectorIndexTooLarge: { timeout: 3000 },
   SearchIndexTooLarge: { timeout: 3000 },
@@ -235,7 +229,7 @@ export class WebSocketManager {
 
     // backoff for unknown errors
     this.defaultInitialBackoff = 1000;
-    this.maxBackoff = 64000;
+    this.maxBackoff = 16000;
     this.retries = 0;
 
     // Ping messages (sync protocol Pings, not WebSocket protocol Pings) are

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 {
-  updateAiFiles,
+  installAiFiles,
   enableAiFiles,
-  removeAiFiles,
   disableAiFiles,
-  statusAiFiles,
-} from "./lib/ai/index.js";
+  removeAiFiles,
+} 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,61 +30,78 @@ 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)\n\n" +
-      "Files you have edited yourself are detected via content hashing and skipped\n" +
-      "rather than silently overwritten.",
+      "  - Agent skills (installed to each coding agent's native path, configured via convex.json)",
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir, convexDir } = await resolveProjectPaths();
-    await updateAiFiles(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")
-  .summary("Enable Convex AI file staleness/install messages")
+  .summary("Enable Convex AI files")
   .description(
-    "Re-enables AI file staleness/install messages by writing\n" +
-      "`aiFiles.disableStalenessMessage: false` to `convex.json`, then installs\n" +
-      "or refreshes the managed AI files.",
+    "Re-enables Convex AI files by writing `aiFiles.enabled: true` to\n" +
+      "`convex.json`, then installs or refreshes the managed AI files.",
   )
   .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")
   .summary("Update Convex AI files to the latest version")
   .description(
-    "Updates the following files if they exist and have not been locally modified:\n" +
+    "Updates the following to their latest versions:\n" +
       "  - 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" +
-      "Files you have edited yourself are detected via content hashing and skipped\n" +
-      "rather than silently overwritten.\n\n" +
-      "Does not change `aiFiles.disableStalenessMessage` in `convex.json`.\n" +
-      "Run `npx convex ai-files enable` to enable staleness/install messages.",
+      "  - 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 updateAiFiles(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")
-  .summary("Suppress AI file staleness/install messages without removing files")
+  .summary("Disable Convex AI files without removing them")
   .description(
-    "Writes a suppression marker into `convex.json` (`aiFiles.disableStalenessMessage`) so\n" +
-      "`npx convex dev` stops suggesting you install AI files.\n\n" +
+    "Writes `aiFiles.enabled: false` to `convex.json` so `npx convex dev`\n" +
+      "stops prompting to install AI files and suppresses staleness messages.\n\n" +
       "Files already installed are left untouched - use `npx convex ai-files remove`\n" +
       "if you also want to delete them.\n\n" +
       "Run `npx convex ai-files enable` to re-enable at any time.",
   )
   .allowExcessArguments(false)
   .action(async () => {
-    const { projectDir } = await resolveProjectPaths();
-    await disableAiFiles(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")
@@ -97,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")
@@ -112,12 +135,12 @@ const aiRemove = new Command("remove")
       "empty file is deleted. Otherwise the rest of the file is kept.\n\n" +
       "Skills installed from other sources are not affected.\n\n" +
       "Note: after `remove`, `npx convex dev` will suggest reinstalling AI files.\n" +
-      "Use `npx convex ai-files disable` to suppress that prompt without deleting files.",
+      "Use `npx convex ai-files disable` to opt out entirely without deleting files.",
   )
   .allowExcessArguments(false)
   .action(async () => {
     const { projectDir, convexDir } = await resolveProjectPaths();
-    await removeAiFiles(projectDir, convexDir);
+    await removeAiFiles({ projectDir, convexDir });
   });
 
 export const aiFiles = new Command("ai-files")

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;
 \`\`\`