feat(clerk-js,clerk-react,types): Introduce state signals

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }

.changeset/dull-cups-accept.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+[Experimental] Signals

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "620KB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "74KB" },
- { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "55.2KB" },
+ { "path": "./dist/clerk.js", "maxSize": "621KB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "75KB" },
+ { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "57KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
  { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
  "@swc/helpers": "^0.5.17",
  "@zxcvbn-ts/core": "3.0.4",
  "@zxcvbn-ts/language-common": "3.0.4",
+ "alien-signals": "2.0.6",
  "browser-tabs-lock": "1.3.0",
  "copy-to-clipboard": "3.3.3",
  "core-js": "3.41.0",

packages/clerk-js/src/core/clerk.ts

@@ -154,6 +154,7 @@ import {
  Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
  public user: UserResource | null | undefined;
  public __internal_country?: string | null;
  public telemetry: TelemetryCollector | undefined;
+ public readonly __internal_state: State = new State();
 
  protected internal_last_error: ClerkAPIError | null = null;
  // converted to protected environment to support `updateEnvironment` type assertion

packages/clerk-js/src/core/events.ts

@@ -1,20 +1,28 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { BaseResource } from './resources/Base';
+
 export const events = {
  TokenUpdate: 'token:update',
  UserSignOut: 'user:signOut',
  EnvironmentUpdate: 'environment:update',
  SessionTokenResolved: 'session:tokenResolved',
+ ResourceUpdate: 'resource:update',
+ ResourceError: 'resource:error',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type ResourceUpdatePayload = { resource: BaseResource };
+export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
 
 type InternalEvents = {
  [events.TokenUpdate]: TokenUpdatePayload;
  [events.UserSignOut]: null;
  [events.EnvironmentUpdate]: null;
  [events.SessionTokenResolved]: null;
+ [events.ResourceUpdate]: ResourceUpdatePayload;
+ [events.ResourceError]: ResourceErrorPayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

packages/clerk-js/src/core/resources/SignIn.ts

@@ -16,6 +16,7 @@ import type {
  EmailCodeConfig,
  EmailLinkConfig,
  EnterpriseSSOConfig,
+ OAuthStrategy,
  PassKeyConfig,
  PasskeyFactor,
  PhoneCodeConfig,
@@ -27,6 +28,7 @@ import type {
  SamlConfig,
  SignInCreateParams,
  SignInFirstFactor,
+ SignInFutureResource,
  SignInIdentifier,
  SignInJSON,
  SignInJSONSnapshot,
@@ -66,6 +68,7 @@ import {
  clerkVerifyPasskeyCalledBeforeCreate,
  clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -82,6 +85,21 @@ export class SignIn extends BaseResource implements SignInResource {
  createdSessionId: string | null = null;
  userData: UserData = new UserData(null);
 
+ /**
+ * @experimental This experimental API is subject to change.
+ *
+ * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
+ */
+ __internal_future: SignInFuture | null = new SignInFuture(this);
+
+ /**
+ * @internal Only used for internal purposes, and is not intended to be used directly.
+ *
+ * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+ * of `SignIn`.
+ */
+ __internal_basePost = this._basePost.bind(this);
+
  constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
  super();
  this.fromJSON(data);
@@ -451,6 +469,8 @@ export class SignIn extends BaseResource implements SignInResource {
  this.createdSessionId = data.created_session_id;
  this.userData = new UserData(data.user_data);
  }
+
+ eventBus.emit('resource:update', { resource: this });
  return this;
  }
 
@@ -470,3 +490,132 @@ export class SignIn extends BaseResource implements SignInResource {
  };
  }
 }
+
+class SignInFuture implements SignInFutureResource {
+ emailCode = {
+ sendCode: this.sendEmailCode.bind(this),
+ verifyCode: this.verifyEmailCode.bind(this),
+ };
+
+ constructor(readonly resource: SignIn) {}
+
+ get status() {
+ return this.resource.status;
+ }
+
+ async create(params: {
+ identifier?: string;
+ strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl?: string;
+ actionCompleteRedirectUrl?: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: params,
+ });
+
+ return { error: null };
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+ }
+
+ async password({ identifier, password }: { identifier: string; password: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ path: this.resource.pathRoot,
+ body: { identifier, password },
+ });
+ } catch (err) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sendEmailCode({ email }: { email: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (!this.resource.id) {
+ await this.create({ identifier: email });
+ }
+
+ const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
+
+ if (!emailCodeFactor) {
+ throw new Error('Email code factor not found');
+ }
+
+ const { emailAddressId } = emailCodeFactor;
+ await this.resource.__internal_basePost({
+ body: { emailAddressId, strategy: 'email_code' },
+ action: 'prepare_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async verifyEmailCode({ code }: { code: string }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ await this.resource.__internal_basePost({
+ body: { code, strategy: 'email_code' },
+ action: 'attempt_first_factor',
+ });
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+
+ async sso({
+ flow = 'auto',
+ strategy,
+ redirectUrl,
+ redirectUrlComplete,
+ }: {
+ flow?: 'auto' | 'modal';
+ strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+ redirectUrl: string;
+ redirectUrlComplete: string;
+ }): Promise<{ error: unknown }> {
+ eventBus.emit('resource:error', { resource: this.resource, error: null });
+ try {
+ if (flow !== 'auto') {
+ throw new Error('modal flow is not supported yet');
+ }
+
+ const redirectUrlWithAuthToken = SignIn.clerk.buildUrlWithAuth(redirectUrl);
+
+ if (!this.resource.id) {
+ await this.create({
+ strategy,
+ redirectUrl: redirectUrlWithAuthToken,
+ actionCompleteRedirectUrl: redirectUrlComplete,
+ });
+ }
+
+ const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
+
+ if (status === 'unverified' && externalVerificationRedirectURL) {
+ windowNavigate(externalVerificationRedirectURL);
+ }
+ } catch (err: unknown) {
+ eventBus.emit('resource:error', { resource: this.resource, error: err });
+ return { error: err };
+ }
+
+ return { error: null };
+ }
+}

packages/clerk-js/src/core/signals.ts

@@ -0,0 +1,17 @@
+import { computed, signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });
+export const signInErrorSignal = signal<{ errors: unknown }>({ errors: null });
+
+export const signInComputedSignal = computed(() => {
+ const signIn = signInSignal().resource;
+ const errors = signInErrorSignal().errors;
+
+ if (!signIn) {
+ return { errors: null, signIn: null };
+ }
+
+ return { errors, signIn: signIn.__internal_future };
+});

packages/clerk-js/src/core/state.ts

@@ -0,0 +1,33 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus } from './events';
+import type { BaseResource } from './resources/Base';
+import { SignIn } from './resources/SignIn';
+import { signInComputedSignal, signInErrorSignal, signInSignal } from './signals';
+
+export class State implements StateInterface {
+ signInResourceSignal = signInSignal;
+ signInErrorSignal = signInErrorSignal;
+ signInSignal = signInComputedSignal;
+
+ __internal_effect = effect;
+ __internal_computed = computed;
+
+ constructor() {
+ eventBus.on('resource:update', this.onResourceUpdated);
+ eventBus.on('resource:error', this.onResourceError);
+ }
+
+ private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInErrorSignal({ errors: payload.error });
+ }
+ };
+
+ private onResourceUpdated = (payload: { resource: BaseResource }) => {
+ if (payload.resource instanceof SignIn) {
+ this.signInResourceSignal({ resource: payload.resource });
+ }
+ };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
  __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,52 @@
+import type { SignInFutureResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { errors: unknown; signIn: SignInFutureResource | null } | null {
+ useAssertWrappedByClerkProvider('useSignInSignal');
+
+ const clerk = useIsomorphicClerkContext();
+
+ const subscribe = useCallback(
+ (callback: () => void) => {
+ if (!clerk.loaded || !clerk.__internal_state) {
+ return () => {};
+ }
+
+ return clerk.__internal_state.__internal_effect(() => {
+ switch (signal) {
+ case 'signIn':
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+ clerk.__internal_state!.signInSignal();
+ break;
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ callback();
+ });
+ },
+ [clerk, clerk.loaded, clerk.__internal_state],
+ );
+ const getSnapshot = useCallback(() => {
+ if (!clerk.__internal_state) {
+ return null;
+ }
+
+ switch (signal) {
+ case 'signIn':
+ return clerk.__internal_state.signInSignal();
+ default:
+ throw new Error(`Unknown signal: ${signal}`);
+ }
+ }, [clerk.__internal_state]);
+
+ const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return value;
+}
+
+export function useSignInSignal() {
+ return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
  SignUpProps,
  SignUpRedirectOptions,
  SignUpResource,
+ State,
  TaskChooseOrganizationProps,
  UnsubscribeCallback,
  UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
  return this.clerkjs?.billing;
  }
 
+ get __internal_state(): State | undefined {
+ return this.clerkjs?.__internal_state;
+ }
+
  get apiKeys(): APIKeysNamespace | undefined {
  return this.clerkjs?.apiKeys;
  }