.changeset/rotten-falcons-cover.md (1)

1-7: Expand the changeset notes to capture the API surface changes and add a brief migration snippet

The current note only mentions the experimental removal of Signals isLoaded, but this PR also:

• Makes Clerk.__internal_state non-null (via StateProxy pre-load),
• Makes SignIn.__internal_future and SignUp.__internal_future non-null,
• Allows calling finalize() with no args on both futures,
• Ensures React hooks return non-null signals.

Capturing these points will help consumers understand the impact and how to migrate.

Apply this diff to augment the changeset body:

 ---
 '@clerk/clerk-js': minor
 '@clerk/clerk-react': minor
 '@clerk/types': minor
 ---
 
-[Experimental] Signals `isLoaded` removal
+[Experimental] Signals `isLoaded` removal
+
+- Clerk: `__internal_state` is now always defined (non-null). Before ClerkJS is ready, a lightweight StateProxy provides sensible defaults; once ready, it switches to the real State.
+- ClerkJS: `SignIn.__internal_future` and `SignUp.__internal_future` are now always present (non-null).
+- ClerkJS: `SignInFuture.finalize()` and `SignUpFuture.finalize()` can be called without arguments.
+- React: Signal hooks now return non-null signal objects.
+
+Migration:
+- Remove conditional guards for `isLoaded` on signals; the returned objects are always present.
+- Stop checking `Clerk.__internal_state` for null/undefined; it is always available.
+- Calling `finalize()` without arguments is now supported; pass `{ navigate }` only when you need custom navigation.

packages/types/src/clerk.ts (1)

233-239: Document the new non-null guarantee for __internal_state

Since __internal_state is now always defined and backed by a StateProxy pre-load, the JSDoc should reflect the non-null guarantee and briefly explain the behavior to reduce confusion.

   /**
-   * @experimental This experimental API is subject to change.
-   *
-   * Entrypoint for Clerk's Signal API containing resource signals along with accessible versions of `computed()` and
-   * `effect()` that can be used to subscribe to changes from Signals.
+   * @experimental This experimental API is subject to change.
+   *
+   * Entrypoint for Clerk's Signal API containing resource signals, plus `computed()` and `effect()` helpers.
+   * This property is always defined. Before ClerkJS is ready, it is backed by an internal StateProxy that
+   * provides sensible defaults and forwards calls once ClerkJS has loaded.
    */
   __internal_state: State;

packages/types/src/signIn.ts (2)

127-132: Make __internal_future read-only in the public type

This property is initialized once per resource and should not be reassigned by consumers. Marking it readonly communicates intent and helps with type safety.

   /**
    * @internal
    */
-  __internal_future: SignInFutureResource;
+  readonly __internal_future: SignInFutureResource;

---

159-160: Add null to the finalize signature for JS null-safety

A quick search for finalize(null) returned no hits, so there are no internal call sites relying on passing null. It’s safe to expand the signature to accommodate JS consumers and avoid a potential destructuring TypeError at runtime.

• File: packages/types/src/signIn.ts
Lines: 159–160
Update the finalize declaration:

-  finalize: (params?: { navigate?: SetActiveNavigate }) => Promise<{ error: unknown }>;
+  finalize: (params?: { navigate?: SetActiveNavigate } | null) => Promise<{ error: unknown }>;

packages/clerk-js/src/core/resources/SignIn.ts (2)

94-95: Mark __internal_future as readonly

This future instance is conceptually immutable per SignIn instance. Marking it readonly prevents accidental reassignment and matches the public type suggestion.

-  __internal_future: SignInFuture = new SignInFuture(this);
+  readonly __internal_future: SignInFuture = new SignInFuture(this);

---

641-649: Harden finalize against null params from JS callers

Current destructuring with a default value throws if null is passed. This change is harmless for TS and more robust for JS.

-  async finalize({ navigate }: { navigate?: SetActiveNavigate } = {}): Promise<{ error: unknown }> {
+  async finalize(params?: { navigate?: SetActiveNavigate } | null): Promise<{ error: unknown }> {
+    const navigate = params?.navigate;
     return runAsyncResourceTask(this.resource, async () => {
       if (!this.resource.createdSessionId) {
         throw new Error('Cannot finalize sign-in without a created session.');
       }
 
       await SignIn.clerk.setActive({ session: this.resource.createdSessionId, navigate });
     });
   }

Happy to add targeted tests for:

• Calling __internal_future.finalize() with undefined and with { navigate },
• Error path when createdSessionId is missing,
• Ensuring __internal_future is always present on a fresh SignIn instance.

packages/clerk-js/src/core/resources/SignUp.ts (2)

90-91: Mark __internal_future as readonly

Same rationale as SignIn: the future should be immutable after construction.

-  __internal_future: SignUpFuture = new SignUpFuture(this);
+  readonly __internal_future: SignUpFuture = new SignUpFuture(this);

---

542-550: Null-safe finalize for JS callers and parity with SignIn

Avoid runtime errors on finalize(null) from JS. This mirrors the suggested hardening for SignInFuture.

-  async finalize({ navigate }: { navigate?: SetActiveNavigate } = {}): Promise<{ error: unknown }> {
+  async finalize(params?: { navigate?: SetActiveNavigate } | null): Promise<{ error: unknown }> {
+    const navigate = params?.navigate;
     return runAsyncResourceTask(this.resource, async () => {
       if (!this.resource.createdSessionId) {
         throw new Error('Cannot finalize sign-up without a created session.');
       }
 
       await SignUp.clerk.setActive({ session: this.resource.createdSessionId, navigate });
     });
   }

I can also add tests that assert:

• finalize() works without args and with { navigate },
• Error thrown when createdSessionId is absent,
• __internal_future is always defined on a fresh SignUp.

packages/types/src/signUp.ts (1)

121-125: Consider making __internal_future readonly.
The property reference itself should not change after initialization; the underlying resource can mutate. Marking it readonly improves type safety.

-  __internal_future: SignUpFutureResource;
+  readonly __internal_future: SignUpFutureResource;

packages/react/src/hooks/useClerkSignal.ts (3)

24-31: Subscribe when not loaded: proactively listen for status to avoid missing the transition.
Today, when clerk.loaded === false, subscribe returns a noop and re-subscribes later via a new callback identity. That works but is brittle. Prefer subscribing to the status event and invoking callback() upon ready, guaranteeing useSyncExternalStore updates exactly when Clerk loads.

   const subscribe = useCallback(
     (callback: () => void) => {
-      if (!clerk.loaded) {
-        return () => {};
-      }
-
-      return clerk.__internal_state.__internal_effect(() => {
+      if (!clerk.loaded) {
+        const unsubscribe = clerk.on('status', s => {
+          if (s === 'ready') {
+            unsubscribe();
+            callback();
+          }
+        });
+        return unsubscribe;
+      }
+
+      return clerk.__internal_state.__internal_effect(() => {
         switch (signal) {
           case 'signIn':
             clerk.__internal_state.signInSignal();
             break;
           case 'signUp':
             clerk.__internal_state.signUpSignal();
             break;
           default:
             throw new Error(`Unknown signal: ${signal}`);
         }
         callback();
       });
     },
     [clerk, clerk.loaded, clerk.__internal_state],
   );

Also applies to: 33-37

---

17-20: Add JSDoc for public hook overloads.
Per guidelines, public APIs should have JSDoc. Briefly document that the hook returns non-null reactive signal objects even before Clerk loads (backed by StateProxy).

-function useClerkSignal(signal: 'signIn'): NonNullSignInSignal;
+/**
+ * Returns a non-null, reactive SignIn signal backed by a proxy until Clerk loads.
+ */
+function useClerkSignal(signal: 'signIn'): NonNullSignInSignal;
-function useClerkSignal(signal: 'signUp'): NonNullSignUpSignal;
+/**
+ * Returns a non-null, reactive SignUp signal backed by a proxy until Clerk loads.
+ */
+function useClerkSignal(signal: 'signUp'): NonNullSignUpSignal;

---

1-69: Please add tests for the new non-null contract.

• Preload scenario: before Clerk loads, useClerkSignal('signIn'|'signUp') returns objects with errors, fetchStatus, and callable methods that don't throw on access.
• Transition scenario: after simulating Clerk load, the hook reflects real state and methods delegate to ClerkJS.
• SSR safety: server-render path should not invoke proxy methods; ensure snapshots render without throwing.

I can draft RTL/Jest tests for the hook with a mocked IsomorphicClerk and a fake StateProxy. Want me to push a test file?

packages/react/src/stateProxy.ts (1)

22-34: Document StateProxy as internal and its guarantees.
Add a brief JSDoc stating that it:

• Implements State
• Returns stable object identities per accessor
• Defers method invocations until Clerk is loaded
• Throws meaningful errors in unsupported environments

-export class StateProxy implements State {
+/**
+ * @internal
+ * A lightweight proxy implementing Clerk `State` that exposes stable signal objects and
+ * defers method calls until ClerkJS is loaded.
+ */
+export class StateProxy implements State {

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/types/src/signUp.ts (2)

121-125: Internal future on SignUpResource aligns with runtime; good addition.
This makes the API shape consistent with ClerkJS and enables gating via proxies.

---

135-136: Optional finalize params: aligns types with runtime defaults.
This change unblocks calling finalize() without args. Please ensure related JSDoc mentions the default navigation behavior when params are omitted.

Would you like me to update/add JSDoc snippets in both @clerk/types and clerk-js to document the default behavior?

packages/react/src/isomorphicClerk.ts (2)

59-59: StateProxy integration looks correct.
Import, field declaration, and constructor initialization are straightforward and side-effect free.

Also applies to: 162-162, 255-256

---

729-731: Non-null __internal_state with fallback is the right call.
Returning clerkjs.__internal_state when loaded and a StateProxy otherwise satisfies the new non-null contract for hooks and consumers.

packages/react/src/hooks/useClerkSignal.ts (2)

7-16: Non-null signal types are well-formed.
The Omit + NonNullable pattern cleanly removes nullability from signIn/signUp while preserving the rest of the shape.

---

49-52: Snapshot reads against non-null state are correct.
Directly reading the signals from __internal_state matches the new contract and avoids unsafe non-null assertions.

packages/react/src/stateProxy.ts (2)

78-83: Explicit errors for internal reactivity APIs pre-load are acceptable.
Throwing on __internal_effect/__internal_computed before load is fine given the hook prevents these paths until loaded === true.

---

35-75: Default signal shapes: verify parity with ClerkJS to avoid shape drift.
Ensure status literals and method keys match ClerkJS’ runtime signals (needs_identifier, missing_requirements, availableStrategies, nested emailCode/resetPasswordEmailCode APIs). If ClerkJS changes, this proxy should be updated in lockstep.

I can add a small type-level test that asserts StateProxy['signInSignal']() satisfies ReturnType<LoadedClerk['__internal_state']['signInSignal']> to catch drift at compile time. Want me to add it?

packages/react/src/stateProxy.ts (1)

96-101: SSR hang resolved — gated methods now fail fast off-browser.

Good job addressing the prior SSR hang by checking inBrowser() before awaiting addOnLoaded. This prevents unresolved promises during SSR. Nothing else needed here.

packages/react/src/stateProxy.ts (7)

99-101: Optional: add a timeout guard around addOnLoaded to avoid edge-case deadlocks.

If ClerkJS fails to load (network, CSP, ad blockers), awaiting addOnLoaded can still hang indefinitely in the browser. Consider a short timeout with an actionable error.

-      if (!this.isomorphicClerk.loaded) {
-        await new Promise<void>(resolve => this.isomorphicClerk.addOnLoaded(resolve));
-      }
+      if (!this.isomorphicClerk.loaded) {
+        const timeoutMs = 10_000;
+        await Promise.race([
+          new Promise<void>(resolve => this.isomorphicClerk.addOnLoaded(resolve)),
+          new Promise<void>((_, reject) =>
+            setTimeout(
+              () =>
+                reject(
+                  new Error(
+                    `Clerk did not load within ${timeoutMs}ms. Verify that <ClerkProvider> is mounted and ClerkJS is reachable.`,
+                  ),
+                ),
+              timeoutMs,
+            ),
+          ),
+        ]);
+      }

---

93-105: Tighten gateMethod typing to match original return shape and avoid double-wrapped Promises.

Using Promise<ReturnType<F>> can become Promise<Promise<R>> when F already returns a Promise (very likely here). Prefer Awaited<ReturnType<F>> to preserve the original function’s surface type.

   private gateMethod<T extends object, K extends keyof T & string>(getTarget: () => T, key: K) {
-    type F = Extract<T[K], (...args: unknown[]) => unknown>;
-    return (async (...args: Parameters<F>): Promise<ReturnType<F>> => {
+    type F = Extract<T[K], (...args: unknown[]) => unknown>;
+    return (async (...args: Parameters<F>): Promise<Awaited<ReturnType<F>>> => {
       if (!inBrowser()) {
         return errorThrower.throw(`Attempted to call a method (${key}) that is not supported on the server.`);
       }
       if (!this.isomorphicClerk.loaded) {
         await new Promise<void>(resolve => this.isomorphicClerk.addOnLoaded(resolve));
       }
       const t = getTarget();
       return (t[key] as (...args: Parameters<F>) => ReturnType<F>).apply(t, args);
-    }) as F;
+    }) as F;
   }

---

27-35: Add explicit return types and mark public API surface explicitly.

Per guidelines, explicitly annotate return types for public methods and type the cached proxies accordingly.

-  private readonly signInSignalProxy = this.buildSignInProxy();
-  private readonly signUpSignalProxy = this.buildSignUpProxy();
+  private readonly signInSignalProxy: ReturnType<State['signInSignal']> = this.buildSignInProxy();
+  private readonly signUpSignalProxy: ReturnType<State['signUpSignal']> = this.buildSignUpProxy();

-  signInSignal() {
+  public signInSignal(): ReturnType<State['signInSignal']> {
     return this.signInSignalProxy;
   }
-  signUpSignal() {
+  public signUpSignal(): ReturnType<State['signUpSignal']> {
     return this.signUpSignalProxy;
   }

---

37-61: Annotate helper builders’ return types to lock API shape to State.

This makes it harder for accidental structural drift to creep in and improves editor IntelliSense.

-  private buildSignInProxy() {
+  private buildSignInProxy(): ReturnType<State['signInSignal']> {
     const target = () => this.client.signIn.__internal_future;
@@
-    return {
+    return {
       errors: defaultErrors(),
       fetchStatus: 'idle' as const,
       signIn: {
         status: 'needs_identifier' as const,
         availableStrategies: [],
@@
-    };
+    } as ReturnType<State['signInSignal']>;
   }
@@
-  private buildSignUpProxy() {
+  private buildSignUpProxy(): ReturnType<State['signUpSignal']> {
     const target = () => this.client.signUp.__internal_future;
@@
-    return {
+    return {
       errors: defaultErrors(),
       fetchStatus: 'idle' as const,
       signUp: {
         status: 'missing_requirements' as const,
         unverifiedFields: [],
@@
-    };
+    } as ReturnType<State['signUpSignal']>;
   }

Also applies to: 62-78

---

80-85: Unify error handling and make messages actionable for devs.

Use the shared errorThrower for consistent error formatting, and include recovery suggestions.

-  __internal_effect(_: () => void): () => void {
-    throw new Error('__internal_effect called before Clerk is loaded');
-  }
-  __internal_computed<T>(_: (prev?: T) => T): () => T {
-    throw new Error('__internal_computed called before Clerk is loaded');
-  }
+  __internal_effect(_: () => void): () => void {
+    errorThrower.throw(
+      '__internal_effect called before Clerk is loaded. Call this only in the browser after Clerk has loaded.',
+    );
+  }
+  __internal_computed<T>(_: (prev?: T) => T): () => T {
+    errorThrower.throw(
+      '__internal_computed called before Clerk is loaded. Call this only in the browser after Clerk has loaded.',
+    );
+  }

---

87-91: Improve the client-not-ready error with context and guidance.

The current message is terse. Provide actionable context to reduce support load.

-    if (!c) throw new Error('Clerk client not ready');
+    if (!c) {
+      throw new Error(
+        'Clerk client is not ready. If you are on the server, avoid calling State methods; otherwise, wait for Clerk to load (e.g., add a loaded listener or use the provided gated methods).',
+      );
+    }

---

24-35: Please add tests for proxy defaults, SSR gating, and handoff to real state.

Given the behavioral changes, unit/integration tests will help prevent regressions:

• SSR: calling any gated method should throw immediately with a helpful message.
• Browser, before load: methods should wait until addOnLoaded resolves, then delegate to ClerkJS.
• Defaults: signInSignal()/signUpSignal() should return stable default shapes (errors structure, fetchStatus, status).
• Handoff: after load, ensure calls bypass the proxy and hit clerkjs.__internal_state.
• Error propagation: downstream errors from ClerkJS methods are surfaced unchanged through the proxy.

Would you like me to scaffold Jest tests that mock IsomorphicClerk.addOnLoaded, loaded, and client to cover these cases?

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.