convex 1.42.2 → 1.43.0-alpha.0

package/src/react/auth_websocket.test.tsx

@@ -8,6 +8,7 @@ import {
   withInMemoryWebSocket,
 } from "../browser/sync/client_node_test_helpers.js";
 import { ConvexReactClient, ConvexReactClientOptions } from "./index.js";
+import { BaseConvexClient } from "../browser/index.js";
 import waitForExpect from "wait-for-expect";
 import { anyApi } from "../server/index.js";
 import { Long } from "../vendor/long.js";
@@ -17,12 +18,21 @@ import {
   WireServerMessage,
 } from "../browser/sync/protocol.js";
 
-const testReactClient = (address: string, options?: ConvexReactClientOptions) =>
-  new ConvexReactClient(address, {
+const testReactClient = (
+  address: string,
+  options?: ConvexReactClientOptions,
+) => {
+  const client = new ConvexReactClient(address, {
     webSocketConstructor: nodeWebSocket,
     unsavedChangesWarning: false,
     ...options,
   });
+  const baseClient = client.sync;
+  if (!(baseClient instanceof BaseConvexClient)) {
+    throw new Error("Expected `sync` to be a `BaseConvexClient`");
+  }
+  return { client, baseClient };
+};
 
 // Disabled due to flakes in CI
 // https://linear.app/convex/issue/ENG-7052/re-enable-auth-websocket-client-tests
@@ -33,7 +43,7 @@ describe.sequential.skip("auth websocket tests", () => {
   // with a constant token provider.
   test("Authenticate via valid static token", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
 
       const tokenFetcher = vi.fn(async () =>
         jwtEncode({ iat: 1234500, exp: 1244500 }, "secret"),
@@ -45,7 +55,7 @@ describe.sequential.skip("auth websocket tests", () => {
       expect((await receive()).type).toEqual("Authenticate");
       expect((await receive()).type).toEqual("ModifyQuerySet");
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       send({
         type: "Transition",
@@ -73,7 +83,7 @@ describe.sequential.skip("auth websocket tests", () => {
   // This happens when a user opens a page after their cached token expired
   test("Reauthenticate after token expiration with versioning", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
 
       let token = jwtEncode({ iat: 1234500, exp: 1244500 }, "wobabloobla");
       const fetchToken = async () => token;
@@ -106,7 +116,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: token,
       });
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       // Server accepts new token
       send({
@@ -138,7 +148,7 @@ describe.sequential.skip("auth websocket tests", () => {
   // fetch from a cache (say due to Prevent Cross Site tracking)
   test("Reauthenticate after token cache failure", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
 
       const freshToken = jwtEncode({ iat: 1234500, exp: 1244500 }, "secret");
       const tokenFetcher = vi.fn(
@@ -158,7 +168,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: freshToken,
       });
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       // Server accepts new token
       send({
@@ -189,7 +199,7 @@ describe.sequential.skip("auth websocket tests", () => {
   // This is usually a misconfigured server rejecting any token
   test("Fail when tokens are always rejected", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
-      const client = testReactClient(address);
+      const { client } = testReactClient(address);
 
       const consoleSpy = vi
         .spyOn(global.console, "error")
@@ -287,7 +297,7 @@ describe.sequential.skip("auth websocket tests", () => {
   // it's authed but it cannot fetch a token at all.
   test("Fail when tokens cannot be fetched", async () => {
     await withInMemoryWebSocket(async ({ address, receive }) => {
-      const client = testReactClient(address);
+      const { client } = testReactClient(address);
       const tokenFetcher = vi.fn(async () => null);
       const onAuthChange = vi.fn();
       void client.setAuth(tokenFetcher, onAuthChange);
@@ -307,7 +317,7 @@ describe.sequential.skip("auth websocket tests", () => {
 
   test("Client is protected against token rejection race", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
 
       const badToken = jwtEncode({ iat: 1234500, exp: 1244500 }, "wobalooba");
       const badTokenFetcher = vi.fn(async () => badToken);
@@ -319,7 +329,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: badToken,
       });
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       const goodToken = jwtEncode({ iat: 1234500, exp: 1244500 }, "secret");
       const goodTokenFetcher = vi.fn(async () => goodToken);
@@ -379,7 +389,7 @@ describe.sequential.skip("auth websocket tests", () => {
   // comes back while the client is waiting for server validation of the new token.
   test("Client ignores non-auth responses for token validation", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
       const ts = Math.ceil(Date.now() / 1000);
       const initialToken = jwtEncode({ iat: ts, exp: ts + 1000 }, "token1");
       const freshToken = jwtEncode({ iat: ts, exp: ts + 1000 }, "token2");
@@ -398,7 +408,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: initialToken,
       });
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       send({
         type: "Transition",
@@ -445,7 +455,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: freshToken,
       });
 
-      const querySetVersion2 = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion2 = baseClient["remoteQuerySet"]["version"];
 
       send({
         type: "Transition",
@@ -478,7 +488,7 @@ describe.sequential.skip("auth websocket tests", () => {
   test("Client maintains connection when refetch occurs during reauth attempt", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
       vi.useFakeTimers();
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
       // In this test we're going to simulate `fetchToken` taking a long time (1s)
       // so we can test race conditions, so the issued time will be 1s after the
       // fetched time.
@@ -543,7 +553,7 @@ describe.sequential.skip("auth websocket tests", () => {
         baseVersion: 0,
         token: initialToken,
       });
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       send({
         type: "Transition",
@@ -659,7 +669,7 @@ describe.sequential.skip("auth websocket tests", () => {
   // unauthenticated state.
   test("Client retries token validation on error", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
       const ts = Math.ceil(Date.now() / 1000);
       const token1 = jwtEncode({ iat: ts, exp: ts + 60 }, "token1");
       const token2 = jwtEncode({ iat: ts, exp: ts + 60 }, "token2");
@@ -674,7 +684,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: token1,
       });
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       send({
         type: "Transition",
@@ -751,7 +761,7 @@ describe.sequential.skip("auth websocket tests", () => {
 
   test("Authentication runs first", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
 
       const token1 = jwtEncode({ iat: 1234500, exp: 1244500 }, "secret");
       const tokenFetcher = vi.fn(async () => token1);
@@ -762,7 +772,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: token1,
       });
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       send({
         type: "Transition",
@@ -792,7 +802,7 @@ describe.sequential.skip("auth websocket tests", () => {
 
   test("Auth pause doesn't prevent unsubscribing from queries", async () => {
     await withInMemoryWebSocket(async ({ address, receive, send }) => {
-      const client = testReactClient(address);
+      const { client, baseClient } = testReactClient(address);
 
       const token1 = jwtEncode({ iat: 1234500, exp: 1244500 }, "secret");
       const tokenFetcher = vi.fn(async () => token1);
@@ -807,7 +817,7 @@ describe.sequential.skip("auth websocket tests", () => {
         token: token1,
       });
 
-      const querySetVersion = client.sync["remoteQuerySet"]["version"];
+      const querySetVersion = baseClient["remoteQuerySet"]["version"];
 
       send({
         type: "Transition",
@@ -829,7 +839,7 @@ describe.sequential.skip("auth websocket tests", () => {
       });
 
       await waitForExpect(() => {
-        expect(client.sync["remoteQuerySet"]["version"].identity).toEqual(1);
+        expect(baseClient["remoteQuerySet"]["version"].identity).toEqual(1);
       });
 
       let resolve: (value: string) => void;
@@ -882,7 +892,7 @@ describe.sequential.skip("auth websocket tests", () => {
 
   test("Local state resume doesn't cause duplicate AddQuery", async () => {
     await withInMemoryWebSocket(async ({ address, receive }) => {
-      const client = testReactClient(address);
+      const { client } = testReactClient(address);
 
       // First we subscribe
       client.watchQuery(anyApi.myQuery.default).onUpdate(() => {});
@@ -923,7 +933,7 @@ describe.sequential.skip("auth websocket tests", () => {
 
   test("Local state resume doesn't send both Add and Remove", async () => {
     await withInMemoryWebSocket(async ({ address, receive }) => {
-      const client = testReactClient(address);
+      const { client } = testReactClient(address);
 
       // First we subscribe to kick off connect.
       client.watchQuery(anyApi.myQuery.default).onUpdate(() => {});
@@ -978,7 +988,7 @@ describe.sequential.skip("auth websocket tests", () => {
 
   test("Local state resume refcounts", async () => {
     await withInMemoryWebSocket(async ({ address, receive }) => {
-      const client = testReactClient(address);
+      const { client } = testReactClient(address);
 
       // First we subscribe to kick off connect.
       client.watchQuery(anyApi.myQuery.default).onUpdate(() => {});
@@ -1034,7 +1044,7 @@ describe.sequential.skip("auth websocket tests", () => {
 
   test("Local state restart doesn't send both Add and Remove", async () => {
     await withInMemoryWebSocket(async ({ address, receive }) => {
-      const client = testReactClient(address);
+      const { client } = testReactClient(address);
 
       // Set slow auth, causing pause while connecting
       let resolve: (value: string) => void;
@@ -1073,7 +1083,7 @@ describe.sequential.skip("auth websocket tests", () => {
 describe.sequential("authMode WebSocket", () => {
   test.each([false, true])("expectAuth: %s", async (expectAuth: boolean) => {
     await withInMemoryWebSocket(async ({ address, receive, close }) => {
-      const client = testReactClient(
+      const { client } = testReactClient(
         address,
         expectAuth ? { expectAuth: true } : {},
       );

package/src/react/client.ts

@@ -12,6 +12,7 @@ import {
   AuthTokenFetcher,
   BaseConvexClientOptions,
   ConnectionState,
+  BaseConvexClientInterface,
 } from "../browser/sync/client.js";
 import type { UserIdentityAttributes } from "../browser/sync/protocol.js";
 import { RequestForQueries, useQueries } from "./use_queries.js";
@@ -295,7 +296,7 @@ export interface ConvexReactClientOptions extends BaseConvexClientOptions {
    *
    * @internal
    */
-  baseClient?: BaseConvexClient;
+  baseClient?: BaseConvexClientInterface;
 
   // FIXME: Ideally we define `ConvexReactClientOptions` as
   // `type ConvexReactClientOptions = BaseConvexClientOptions | { baseClient: BaseConvexClient }`
@@ -313,7 +314,7 @@ export interface ConvexReactClientOptions extends BaseConvexClientOptions {
  */
 export class ConvexReactClient {
   private address: string;
-  private cachedSync?: BaseConvexClient | undefined;
+  private cachedSync?: BaseConvexClientInterface | undefined;
   private cachedPaginatedQueryClient?: PaginatedQueryClient | undefined;
   private listeners: Map<QueryToken | PaginatedQueryToken, Set<() => void>>;
   private options: ConvexReactClientOptions;

package/src/react/client_provided_base_client.test.tsx

@@ -4,53 +4,171 @@ import ws from "ws";
 import { ConvexReactClient } from "./client.js";
 import { anyApi } from "../server/api.js";
 import { BaseConvexClient } from "../browser/index.js";
+import { BaseConvexClientInterface } from "../browser/sync/client.js";
 
 const address = "https://127.0.0.1:3001";
 
-// A minimal subclass of `BaseConvexClient` used to prove that a
-// caller-provided `BaseConvexClient` (of any subclass) can be plugged into a
-// `ConvexReactClient` via the `client` option.
-class MinimalBaseConvexClient extends BaseConvexClient {}
+describe("Creating a ConvexReactClient with a custom base client", () => {
+  describe("with a `BaseConvexClient` subclass", () => {
+    // A minimal subclass of `BaseConvexClient` used to prove that a
+    // caller-provided `BaseConvexClient` (of any subclass) can be plugged into
+    // a `ConvexReactClient` via the `client` option.
+    class MinimalBaseConvexClient extends BaseConvexClient {}
 
-const testBaseConvexClient = () =>
-  new MinimalBaseConvexClient(address, () => {}, {
-    webSocketConstructor: ws as unknown as typeof WebSocket,
-  });
+    const testBaseConvexClient = () =>
+      new MinimalBaseConvexClient(address, () => {}, {
+        webSocketConstructor: ws as unknown as typeof WebSocket,
+      });
 
-describe("ConvexReactClient with a provided BaseConvexClient", () => {
-  test("uses the provided client as its `sync` client", () => {
-    const baseClient = testBaseConvexClient();
-    const client = new ConvexReactClient(address, { baseClient });
-    expect(client.sync).toBe(baseClient);
-  });
+    test("uses the provided client as its `sync` client", () => {
+      const baseClient = testBaseConvexClient();
+      const client = new ConvexReactClient(address, { baseClient });
+      expect(client.sync).toBe(baseClient);
+    });
+
+    test("applies setAdminAuth called before the client is lazily instantiated", () => {
+      const baseClient = testBaseConvexClient();
+      const setAdminAuthSpy = vi.spyOn(baseClient, "setAdminAuth");
+      const client = new ConvexReactClient(address, { baseClient });
+      client.setAdminAuth("admin-token");
+      expect(setAdminAuthSpy).not.toHaveBeenCalled();
+
+      // Accessing `sync` lazily instantiates the client, applying admin auth.
+      expect(client.sync).toBe(baseClient);
+      expect(setAdminAuthSpy).toHaveBeenCalledWith("admin-token", undefined);
+    });
 
-  test("applies setAdminAuth called before the client is lazily instantiated", () => {
-    const baseClient = testBaseConvexClient();
-    const setAdminAuthSpy = vi.spyOn(baseClient, "setAdminAuth");
-    const client = new ConvexReactClient(address, { baseClient });
-    client.setAdminAuth("admin-token");
-    expect(setAdminAuthSpy).not.toHaveBeenCalled();
+    test("queries and mutations work through the provided client", async () => {
+      const baseClient = testBaseConvexClient();
+      const client = new ConvexReactClient(address, { baseClient });
 
-    // Accessing `sync` lazily instantiates the client, applying admin auth.
-    expect(client.sync).toBe(baseClient);
-    expect(setAdminAuthSpy).toHaveBeenCalledWith("admin-token", undefined);
+      void client.mutation(
+        anyApi.myMutation.default,
+        {},
+        {
+          optimisticUpdate: (localStore) => {
+            localStore.setQuery(anyApi.myQuery.default, {}, "queryResult");
+          },
+        },
+      );
+
+      const queryResult = client.query(anyApi.myQuery.default, {});
+      expect(await queryResult).toStrictEqual("queryResult");
+    });
   });
 
-  test("queries and mutations work through the provided client", async () => {
-    const baseClient = testBaseConvexClient();
-    const client = new ConvexReactClient(address, { baseClient });
+  describe("with a from-scratch BaseConvexClientInterface implementation", () => {
+    // A from-scratch (non-subclass) implementation of `BaseConvexClientInterface`.
+    // Unlike `MinimalBaseConvexClient` above, this does not extend
+    // `BaseConvexClient`, so TypeScript forces every public member to be
+    // declared here explicitly — if `BaseConvexClientInterface` ever gains a member,
+    // this class fails to compile until a matching forwarding method is added.
+    class ComposedBaseConvexClient implements BaseConvexClientInterface {
+      private inner: BaseConvexClient;
+
+      constructor(...args: ConstructorParameters<typeof BaseConvexClient>) {
+        this.inner = new BaseConvexClient(...args);
+      }
+
+      addOnTransitionHandler(
+        ...args: Parameters<BaseConvexClient["addOnTransitionHandler"]>
+      ) {
+        return this.inner.addOnTransitionHandler(...args);
+      }
+      setAuth(...args: Parameters<BaseConvexClient["setAuth"]>) {
+        return this.inner.setAuth(...args);
+      }
+      setAdminAuth(...args: Parameters<BaseConvexClient["setAdminAuth"]>) {
+        return this.inner.setAdminAuth(...args);
+      }
+      clearAuth() {
+        return this.inner.clearAuth();
+      }
+      subscribe(...args: Parameters<BaseConvexClient["subscribe"]>) {
+        return this.inner.subscribe(...args);
+      }
+      localQueryResult(
+        ...args: Parameters<BaseConvexClient["localQueryResult"]>
+      ) {
+        return this.inner.localQueryResult(...args);
+      }
+      localQueryResultByToken(
+        ...args: Parameters<BaseConvexClient["localQueryResultByToken"]>
+      ) {
+        return this.inner.localQueryResultByToken(...args);
+      }
+      hasLocalQueryResultByToken(
+        ...args: Parameters<BaseConvexClient["hasLocalQueryResultByToken"]>
+      ) {
+        return this.inner.hasLocalQueryResultByToken(...args);
+      }
+      localQueryLogs(...args: Parameters<BaseConvexClient["localQueryLogs"]>) {
+        return this.inner.localQueryLogs(...args);
+      }
+      queryJournal(...args: Parameters<BaseConvexClient["queryJournal"]>) {
+        return this.inner.queryJournal(...args);
+      }
+      connectionState() {
+        return this.inner.connectionState();
+      }
+      subscribeToConnectionState(
+        ...args: Parameters<BaseConvexClient["subscribeToConnectionState"]>
+      ) {
+        return this.inner.subscribeToConnectionState(...args);
+      }
+      mutation(...args: Parameters<BaseConvexClient["mutation"]>) {
+        return this.inner.mutation(...args);
+      }
+      action(...args: Parameters<BaseConvexClient["action"]>) {
+        return this.inner.action(...args);
+      }
+      close() {
+        return this.inner.close();
+      }
+      get url() {
+        return this.inner.url;
+      }
+    }
+
+    const testBaseConvexClient = () =>
+      new ComposedBaseConvexClient(address, () => {}, {
+        webSocketConstructor: ws as unknown as typeof WebSocket,
+      });
+
+    test("uses the provided client as its `sync` client", () => {
+      const baseClient = testBaseConvexClient();
+      const client = new ConvexReactClient(address, { baseClient });
+      expect(client.sync).toBe(baseClient);
+    });
+
+    test("applies setAdminAuth called before the client is lazily instantiated", () => {
+      const baseClient = testBaseConvexClient();
+      const setAdminAuthSpy = vi.spyOn(baseClient, "setAdminAuth");
+      const client = new ConvexReactClient(address, { baseClient });
+      client.setAdminAuth("admin-token");
+      expect(setAdminAuthSpy).not.toHaveBeenCalled();
+
+      // Accessing `sync` lazily instantiates the client, applying admin auth.
+      expect(client.sync).toBe(baseClient);
+      expect(setAdminAuthSpy).toHaveBeenCalledWith("admin-token", undefined);
+    });
+
+    test("queries and mutations work through the provided client", async () => {
+      const baseClient = testBaseConvexClient();
+      const client = new ConvexReactClient(address, { baseClient });
 
-    void client.mutation(
-      anyApi.myMutation.default,
-      {},
-      {
-        optimisticUpdate: (localStore) => {
-          localStore.setQuery(anyApi.myQuery.default, {}, "queryResult");
+      void client.mutation(
+        anyApi.myMutation.default,
+        {},
+        {
+          optimisticUpdate: (localStore) => {
+            localStore.setQuery(anyApi.myQuery.default, {}, "queryResult");
+          },
         },
-      },
-    );
+      );
 
-    const queryResult = client.query(anyApi.myQuery.default, {});
-    expect(await queryResult).toStrictEqual("queryResult");
+      const queryResult = client.query(anyApi.myQuery.default, {});
+      expect(await queryResult).toStrictEqual("queryResult");
+    });
   });
 });

package/src/server/audit_logging.test.ts

@@ -24,6 +24,7 @@ describe("cloneWithSentinels", () => {
       agent: log.vars.userAgent,
       ts: log.vars.now,
       reqId: log.vars.requestId,
+      admin: log.internalVars.convexActor,
       note: "hello",
     };
     const result = cloneWithSentinels(input);
@@ -33,6 +34,7 @@ describe("cloneWithSentinels", () => {
       agent: { $var: "userAgent" },
       ts: { $var: "now" },
       reqId: { $var: "requestId" },
+      admin: { $var: "convexActor" },
       note: "hello",
     });
   });

package/src/server/components/index.test.ts

@@ -1,6 +1,7 @@
 import { expect, test } from "vitest";
 
-import { defineApp } from "./index.js";
+import { v } from "../../values/index.js";
+import { defineApp, defineComponent } from "./index.js";
 
 test("app.use throws on empty component name", () => {
   const app = defineApp() as any;
@@ -14,3 +15,34 @@ test("app.use throws on empty component name", () => {
     /component name cannot be empty/i,
   );
 });
+
+test("app.use requires the options arg only when a component declares required env vars", () => {
+  const app = defineApp();
+  const requiredEnv = defineComponent("requiredEnv", {
+    env: { THING_I_NEED: v.string() },
+  });
+  const optionalEnv = defineComponent("optionalEnv", {
+    env: { THING_I_WANT: v.optional(v.string()) },
+  });
+  const emptyEnv = defineComponent("emptyEnv", { env: {} });
+
+  // Type-only assertions. Never invoked: `app.use` needs a runtime component
+  // with a `componentDefinitionPath`, which these plain definitions lack.
+  void (() => {
+    // @ts-expect-error a required env var means the options arg can't be dropped
+    app.use(requiredEnv);
+    // @ts-expect-error nor can `env` itself be omitted
+    app.use(requiredEnv, {});
+    app.use(requiredEnv, { env: { THING_I_NEED: "a string" } });
+
+    // With only optional env vars, both forms are allowed.
+    app.use(optionalEnv);
+    app.use(optionalEnv, { env: {} });
+    app.use(optionalEnv, { env: { THING_I_WANT: "a string" } });
+
+    // A component declaring no env vars needs no `env` (and `env: {}` is fine).
+    app.use(emptyEnv);
+    app.use(emptyEnv, {});
+    app.use(emptyEnv, { env: {} });
+  });
+});

package/src/server/components/index.ts

@@ -105,7 +105,7 @@ export type ComponentDefinition<
    */
   use<Definition extends ComponentDefinition<any, any>>(
     definition: Definition,
-    options?: UseOptions<Definition>,
+    ...args: UseArgs<Definition>
   ): InstalledComponent<Definition>;
 
   /**
@@ -136,30 +136,55 @@ type ComponentDefinitionExports<T extends ComponentDefinition<any, any>> =
 type ComponentDefinitionEnv<T extends ComponentDefinition<any, any>> =
   T["__env"];
 
+/**
+ * The names in an {@link EnvDefinition} whose validators are required (not
+ * wrapped in `v.optional(...)`).
+ */
+type RequiredEnvKeys<E extends EnvDefinition> = {
+  [K in keyof E]: E[K] extends Validator<any, "optional", any> ? never : K;
+}[keyof E];
+
 /**
  * Options for installing a component via `app.use()` or `component.use()`.
  *
- * If the component declares required env vars, the `env` property is required.
+ * If the component declares any required env vars, the `env` property is
+ * required. Otherwise it is optional, so that a component with no env vars (or
+ * only optional ones) can be installed without passing `env`.
  */
 type UseOptions<Definition extends ComponentDefinition<any, any>> =
-  keyof ComponentDefinitionEnv<Definition> extends never
-    ? { name?: string; httpPrefix?: string }
+  RequiredEnvKeys<ComponentDefinitionEnv<Definition>> extends never
+    ? {
+        name?: string;
+        httpPrefix?: string;
+        env?: UseOptionsEnv<ComponentDefinitionEnv<Definition>>;
+      }
     : {
         name?: string;
         httpPrefix?: string;
         env: UseOptionsEnv<ComponentDefinitionEnv<Definition>>;
       };
 
+/**
+ * The arguments to `use()` after the component definition.
+ *
+ * When the component declares required env vars the `options` argument is
+ * mandatory (so it can't be dropped to skip the required `env`); otherwise it
+ * is optional.
+ */
+type UseArgs<Definition extends ComponentDefinition<any, any>> =
+  RequiredEnvKeys<ComponentDefinitionEnv<Definition>> extends never
+    ? [options?: UseOptions<Definition>]
+    : [options: UseOptions<Definition>];
+
 type UseOptionsEnv<E extends EnvDefinition> = Expand<
   {
-    [K in keyof E as E[K] extends VOptional<any> ? never : K]:
+    [K in keyof E as E[K] extends Validator<any, "optional", any> ? never : K]:
       | Infer<E[K]>
       | EnvRef;
   } & {
-    [K in keyof E as E[K] extends VOptional<any> ? K : never]?:
-      | Infer<E[K]>
-      | EnvRef
-      | undefined;
+    [K in keyof E as E[K] extends Validator<any, "optional", any>
+      ? K
+      : never]?: Infer<E[K]> | EnvRef | undefined;
   }
 >;
 
@@ -213,11 +238,13 @@ export type EnvDefinition = Record<
  */
 export type EnvFromDefinition<E extends EnvDefinition> = Expand<
   {
-    [K in keyof E as E[K] extends VOptional<any> ? never : K]: Infer<E[K]>;
+    [K in keyof E as E[K] extends Validator<any, "optional", any>
+      ? never
+      : K]: Infer<E[K]>;
   } & {
-    [K in keyof E as E[K] extends VOptional<any> ? K : never]?:
-      | Infer<E[K]>
-      | undefined;
+    [K in keyof E as E[K] extends Validator<any, "optional", any>
+      ? K
+      : never]?: Infer<E[K]> | undefined;
   }
 >;
 
@@ -269,7 +296,7 @@ export type AppDefinition<Env extends EnvDefinition = EnvDefinition> = {
    */
   use<Definition extends ComponentDefinition<any, any>>(
     definition: Definition,
-    options?: UseOptions<Definition>,
+    ...args: UseArgs<Definition>
   ): InstalledComponent<Definition>;
 
   /**