feat(sdks): Add sdkMetadata to Clerk singleton, populate it for each SDK

.changeset/nasty-ties-invite.md

@@ -0,0 +1,13 @@
+---
+'gatsby-plugin-clerk': patch
+'@clerk/clerk-js': patch
+'@clerk/chrome-extension': patch
+'@clerk/fastify': patch
+'@clerk/nextjs': patch
+'@clerk/clerk-react': patch
+'@clerk/remix': patch
+'@clerk/types': patch
+'@clerk/clerk-expo': patch
+---
+
+Introduce a new property on the core Clerk singleton, `sdkMetadata`. This will be populated by each host SDK. This metadata will be used to make logging and debugging easier.

packages/chrome-extension/jest.config.js

@@ -1,3 +1,6 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { name, version } = require('./package.json');
+
 module.exports = {
   displayName: 'clerk-js',
   injectGlobals: true,
@@ -13,4 +16,10 @@ module.exports = {
 
   testRegex: ['/src/.*.test.[jt]sx?$'],
   testPathIgnorePatterns: ['/node_modules/'],
+
+  globals: {
+    __DEV__: true,
+    PACKAGE_NAME: name,
+    PACKAGE_VERSION: version,
+  },
 };

packages/chrome-extension/src/ClerkProvider.tsx

@@ -7,6 +7,11 @@ import type { TokenCache } from './cache';
 import { ChromeStorageCache } from './cache';
 import { buildClerk } from './singleton';
 
+Clerk.sdkMetadata = {
+  name: PACKAGE_NAME,
+  version: PACKAGE_VERSION,
+};
+
 __internal__setErrorThrowerOptions({
   packageName: '@clerk/chrome-extension',
 });

packages/chrome-extension/src/globals.d.ts

@@ -0,0 +1,7 @@
+export {};
+
+declare global {
+  const PACKAGE_NAME: string;
+  const PACKAGE_VERSION: string;
+  const __DEV__: boolean;
+}

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

@@ -41,6 +41,7 @@ import type {
   PublishableKey,
   RedirectOptions,
   Resources,
+  SDKMetadata,
   SetActiveParams,
   SignInProps,
   SignInRedirectOptions,
@@ -144,7 +145,13 @@ const defaultOptions: ClerkOptions = {
 
 export default class Clerk implements ClerkInterface {
   public static mountComponentRenderer?: MountComponentRenderer;
+
   public static version: string = __PKG_VERSION__;
+  public static sdkMetadata: SDKMetadata = {
+    name: __PKG_NAME__,
+    version: __PKG_VERSION__,
+  };
+
   public client?: ClientResource;
   public session?: ActiveSessionResource | null;
   public organization?: OrganizationResource | null;

packages/expo/src/singleton.ts

@@ -2,8 +2,14 @@ import type { FapiRequestInit, FapiResponse } from '@clerk/clerk-js/dist/types/c
 import Clerk from '@clerk/clerk-js/headless';
 import type { HeadlessBrowserClerk } from '@clerk/clerk-react';
 
+import { name, version } from '../package.json';
 import type { TokenCache } from './cache';
 
+const SDK_METADATA = {
+  name,
+  version,
+};
+
 const KEY = '__clerk_client_jwt';
 
 export let clerk: HeadlessBrowserClerk;
@@ -27,6 +33,8 @@ export function buildClerk({ key, tokenCache }: BuildClerkOptions): HeadlessBrow
     // TODO: DO NOT ACCEPT THIS
     clerk = new Clerk(key);
 
+    clerk.sdkMetadata = SDK_METADATA;
+
     // @ts-expect-error
     clerk.__unstable__onBeforeRequest(async (requestInit: FapiRequestInit) => {
       // https://reactnative.dev/docs/0.61/network#known-issues-with-fetch-and-cookie-based-authentication

packages/fastify/tsup.config.ts

@@ -1,5 +1,7 @@
 import { defineConfig } from 'tsup';
 
+import { name, version } from './package.json';
+
 export default defineConfig(overrideOptions => {
   const isProd = overrideOptions.env?.NODE_ENV === 'production';
 
@@ -11,5 +13,10 @@ export default defineConfig(overrideOptions => {
     sourcemap: true,
     format: ['cjs', 'esm'],
     legacyOutput: true,
+    define: {
+      PACKAGE_NAME: `"${name}"`,
+      PACKAGE_VERSION: `"${version}"`,
+      __DEV__: `${!isProd}`,
+    },
   };
 });

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,13 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { name, version } from '../package.json';
+
+const SDK_METADATA = {
+  name,
+  version,
+};
+
 __internal__setErrorThrowerOptions({ packageName: 'gatsby-plugin-clerk' });
 
 export type GatsbyClerkProviderProps = {
@@ -22,6 +29,7 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
     <ReactClerkProvider
       navigate={to => navigate(to)}
       initialState={__clerk_ssr_state || {}}
+      sdkMetadata={SDK_METADATA}
       {...restProps}
     >
       {__clerk_ssr_interstitial_html ? (

packages/nextjs/src/global.d.ts

@@ -6,6 +6,9 @@ declare global {
 }
 
 declare global {
+  const PACKAGE_NAME: string;
+  const PACKAGE_VERSION: string;
+
   namespace NodeJS {
     interface ProcessEnv {
       NEXT_PUBLIC_CLERK_FRONTEND_API: string | undefined;

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,5 +15,9 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
     signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
     afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
     afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+    sdkMetadata: {
+      name: PACKAGE_NAME,
+      version: PACKAGE_VERSION,
+    },
   };
 };

packages/react/src/isomorphicClerk.ts

@@ -198,6 +198,8 @@ export default class IsomorphicClerk {
         await global.Clerk.load(this.options);
       }
 
+      global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
+
       if (global.Clerk?.loaded || global.Clerk?.isReady()) {
         return this.hydrateClerkJS(global.Clerk);
       }

packages/react/src/types.ts

@@ -6,6 +6,7 @@ import type {
   LoadedClerk,
   MultiDomainAndOrProxy,
   PublishableKeyOrFrontendApi,
+  SDKMetadata,
   SessionResource,
   SignInRedirectOptions,
   SignUpRedirectOptions,
@@ -26,6 +27,7 @@ export type IsomorphicClerkOptions = Omit<ClerkOptions, 'isSatellite'> & {
   clerkJSUrl?: string;
   clerkJSVariant?: 'headless' | '';
   clerkJSVersion?: string;
+  sdkMetadata?: SDKMetadata;
 } & PublishableKeyOrFrontendApi &
   MultiDomainAndOrProxy;
 

packages/remix/src/client/RemixClerkProvider.tsx

@@ -2,13 +2,19 @@ import type { IsomorphicClerkOptions } from '@clerk/clerk-react';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
 import React from 'react';
 
+import { name, version } from '../../package.json';
 import { assertValidClerkState, warnForSsr } from '../utils';
 import { ClerkRemixOptionsProvider } from './RemixOptionsContext';
 import type { ClerkState } from './types';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
 export * from '@clerk/clerk-react';
 
+const SDK_METADATA = {
+  name,
+  version,
+};
+
 export type RemixClerkProviderProps = {
   children: React.ReactNode;
   clerkState: ClerkState;
@@ -20,7 +26,7 @@ export type RemixClerkProviderProps = {
  * In the case of a hydration error, the first `navigate` function we get from the `useNavigate` hook will not work
  * because the RemixClerkProvider (which is part of the host app) will unmount before the following useEffect within `navigate` fires:
  * https://github.com/remix-run/react-router/blob/main/packages/react-router/lib/hooks.tsx#L175
- * so isomorphicClerk will initialise with a `navigate` function that will never have `activeRef.current` set to true.
+ * so isomorphicClerk will initialize with a `navigate` function that will never have `activeRef.current` set to true.
  * This variable is just an object ref/cache outside the React rendering cycle that holds a reference to the
  * latest `navigate` function. After a hydration error occurs, RemixClerkProvider will *remount* and this variable
  * will finally get a `navigate` function that has a `activeRef.current` to true so navigation will function as it should.
@@ -81,6 +87,7 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
       <ReactClerkProvider
         navigate={(to: string) => awaitableNavigateRef.current?.(to)}
         initialState={__clerk_ssr_state}
+        sdkMetadata={SDK_METADATA}
         {...mergedProps}
         {...restProps}
       >

packages/types/src/clerk.ts

@@ -22,6 +22,11 @@ import type { DeepPartial, DeepSnakeToCamel } from './utils';
 
 export type InstanceType = 'production' | 'development';
 
+export type SDKMetadata = {
+  name: string;
+  version: string;
+};
+
 export type ListenerCallback = (emission: Resources) => void;
 export type UnsubscribeCallback = () => void;
 export type BeforeEmitCallback = (session?: ActiveSessionResource | null) => void | Promise<any>;
@@ -56,6 +61,12 @@ export interface Clerk {
    */
   version?: string;
 
+  /**
+   * If present, contains information about the SDK that the host application is using.
+   * For example, if Clerk is loaded through `@clerk/nextjs`, this would be `{ name: '@clerk/nextjs', version: '1.0.0' }`
+   */
+  sdkMetadata?: SDKMetadata;
+
   loaded: boolean;
 
   /**