chore(shared,react-router,tanstack-start): Create shared environment variable retrieval function (#4985)

Author: wobsoriano

.changeset/eleven-cougars-film.md

@@ -0,0 +1,13 @@
+---
+"@clerk/shared": minor
+---
+
+Introduce unified environment variable handling across all supported platforms
+
+Usage:
+
+```ts
+import { getEnvVariable } from '@clerk/shared/getEnvVariable'
+
+const publishableKey = getEnvVariable('CLERK_PUBLISHABLE_KEY')
+```

.changeset/unlucky-gifts-obey.md

@@ -0,0 +1,6 @@
+---
+'@clerk/tanstack-start': patch
+'@clerk/react-router': patch
+---
+
+Internal changes to use new `getEnvVariable` utility from `@clerk/shared`

packages/react-router/src/ssr/loadOptions.ts

@@ -1,10 +1,11 @@
 import { createClerkRequest } from '@clerk/backend/internal';
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isDevelopmentFromSecretKey } from '@clerk/shared/keys';
 import { isHttpOrHttps, isProxyUrlRelative } from '@clerk/shared/proxy';
 import { handleValueOrFn } from '@clerk/shared/utils';
 
-import { getEnvVariable, getPublicEnvVariables } from '../utils/env';
+import { getPublicEnvVariables } from '../utils/env';
 import { noSecretKeyError, satelliteAndMissingProxyUrlAndDomain, satelliteAndMissingSignInUrl } from '../utils/errors';
 import type { LoaderFunctionArgs, RootAuthLoaderOptions } from './types';
 import { patchRequest } from './utils';

packages/react-router/src/utils/env.ts

@@ -1,59 +1,7 @@
+import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext } from 'react-router';
 
-type CloudflareEnv = { env: Record<string, string> };
-
-const hasCloudflareProxyContext = (context: any): context is { cloudflare: CloudflareEnv } => {
-  return !!context?.cloudflare?.env;
-};
-
-const hasCloudflareContext = (context: any): context is CloudflareEnv => {
-  return !!context?.env;
-};
-
-/**
- *
- * Utility function to get env variables across Node and Edge runtimes.
- *
- * @param name
- * @returns string
- */
-export const getEnvVariable = (name: string, context: AppLoadContext | undefined): string => {
-  // Node envs
-  if (typeof process !== 'undefined' && process.env && typeof process.env[name] === 'string') {
-    return process.env[name];
-  }
-
-  // @ts-expect-error - Vite specific
-  if (typeof import.meta !== 'undefined' && import.meta.env && typeof import.meta.env[name] === 'string') {
-    // @ts-expect-error - Vite specific
-    return import.meta.env[name];
-  }
-
-  if (hasCloudflareProxyContext(context)) {
-    return context.cloudflare.env[name] || '';
-  }
-
-  // Cloudflare
-  if (hasCloudflareContext(context)) {
-    return context.env[name] || '';
-  }
-
-  // Check whether the value exists in the context object directly
-  if (context && typeof context[name] === 'string') {
-    return context[name];
-  }
-
-  // Cloudflare workers
-  try {
-    return globalThis[name as keyof typeof globalThis];
-  } catch {
-    // This will raise an error in Cloudflare Pages
-  }
-
-  return '';
-};
-
 export const getPublicEnvVariables = (context: AppLoadContext | undefined) => {
   return {
     publishableKey:

packages/shared/global.d.ts

@@ -2,3 +2,11 @@ declare const PACKAGE_NAME: string;
 declare const PACKAGE_VERSION: string;
 declare const JS_PACKAGE_VERSION: string;
 declare const __DEV__: boolean;
+
+interface ImportMetaEnv {
+  readonly [key: string]: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

packages/shared/package.json

@@ -115,6 +115,7 @@
     "object",
     "oauth",
     "web3",
+    "getEnvVariable",
     "pathMatcher"
   ],
   "scripts": {

packages/shared/src/getEnvVariable.ts

@@ -0,0 +1,50 @@
+type CloudflareEnv = { env: Record<string, string> };
+
+const hasCloudflareProxyContext = (context: any): context is { cloudflare: CloudflareEnv } => {
+  return !!context?.cloudflare?.env;
+};
+
+const hasCloudflareContext = (context: any): context is CloudflareEnv => {
+  return !!context?.env;
+};
+
+/**
+ * Retrieves an environment variable across runtime environments.
+ * @param name - The environment variable name to retrieve
+ * @param context - Optional context object that may contain environment values
+ * @returns The environment variable value or empty string if not found
+ */
+export const getEnvVariable = (name: string, context?: Record<string, any>): string => {
+  // Node envs
+  if (typeof process !== 'undefined' && process.env && typeof process.env[name] === 'string') {
+    return process.env[name];
+  }
+
+  // Vite specific
+  if (typeof import.meta !== 'undefined' && import.meta.env && typeof import.meta.env[name] === 'string') {
+    return import.meta.env[name];
+  }
+
+  if (hasCloudflareProxyContext(context)) {
+    return context.cloudflare.env[name] || '';
+  }
+
+  // Cloudflare
+  if (hasCloudflareContext(context)) {
+    return context.env[name] || '';
+  }
+
+  // Check whether the value exists in the context object directly
+  if (context && typeof context[name] === 'string') {
+    return context[name];
+  }
+
+  // Cloudflare workers
+  try {
+    return globalThis[name as keyof typeof globalThis];
+  } catch {
+    // This will raise an error in Cloudflare Pages
+  }
+
+  return '';
+};

packages/shared/src/index.ts

@@ -35,4 +35,5 @@ export * from './object';
 export * from './logger';
 export { createWorkerTimers } from './workerTimers';
 export { DEV_BROWSER_JWT_KEY, extractDevBrowserJWTFromURL, setDevBrowserJWTInURL } from './devBrowser';
+export { getEnvVariable } from './getEnvVariable';
 export * from './pathMatcher';

packages/shared/tsup.config.ts

@@ -24,6 +24,7 @@ export default defineConfig(overrideOptions => {
     minify: false,
     sourcemap: true,
     dts: true,
+    target: 'es2020',
     external: ['react', 'react-dom'],
     esbuildPlugins: [WebWorkerMinifyPlugin as any],
     define: {

packages/tanstack-start/src/server/constants.ts

@@ -1,11 +1,12 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { getEvent } from 'vinxi/http';
 
-import { getEnvVariable, getPublicEnvVariables } from '../utils/env';
+import { getPublicEnvVariables } from '../utils/env';
 
 export const commonEnvs = () => {
   const event = getEvent();
-  const publicEnvs = getPublicEnvVariables(event);
+  const publicEnvs = getPublicEnvVariables(event.context);
 
   return {
     // Public environment variables
@@ -21,16 +22,16 @@ export const commonEnvs = () => {
     TELEMETRY_DEBUG: publicEnvs.telemetryDebug,
 
     // Server-only environment variables
-    API_VERSION: getEnvVariable('CLERK_API_VERSION', 'v1', event),
-    SECRET_KEY: getEnvVariable('CLERK_SECRET_KEY', '', event),
-    ENCRYPTION_KEY: getEnvVariable('CLERK_ENCRYPTION_KEY', '', event),
-    CLERK_JWT_KEY: getEnvVariable('CLERK_JWT_KEY', '', event),
-    API_URL: getEnvVariable('CLERK_API_URL', '', event) || apiUrlFromPublishableKey(publicEnvs.publishableKey),
+    API_VERSION: getEnvVariable('CLERK_API_VERSION', event.context) || 'v1',
+    SECRET_KEY: getEnvVariable('CLERK_SECRET_KEY', event.context),
+    ENCRYPTION_KEY: getEnvVariable('CLERK_ENCRYPTION_KEY', event.context),
+    CLERK_JWT_KEY: getEnvVariable('CLERK_JWT_KEY', event.context),
+    API_URL: getEnvVariable('CLERK_API_URL', event.context) || apiUrlFromPublishableKey(publicEnvs.publishableKey),
 
     SDK_METADATA: {
       name: PACKAGE_NAME,
       version: PACKAGE_VERSION,
-      environment: getEnvVariable('NODE_ENV', '', event),
+      environment: getEnvVariable('NODE_ENV', event.context),
     },
   } as const;
 };