fix(nuxt): derive apiUrl from publishable key like other SDKs (#8208)

Author: wyattjoh

.changeset/nuxt-derive-api-url.md

@@ -0,0 +1,5 @@
+---
+"@clerk/nuxt": patch
+---
+
+Derive `apiUrl` from the publishable key using `apiUrlFromPublishableKey()`, matching the behavior of other Clerk SDKs (`@clerk/nextjs`, `@clerk/astro`, etc.). Staging publishable keys (with `.accountsstage.dev`) now automatically route to `https://api.clerkstage.dev` without requiring a manual `NUXT_PUBLIC_CLERK_API_URL` override. Explicit `apiUrl` configuration still takes priority.

packages/nuxt/src/module.ts

@@ -74,7 +74,7 @@ export default defineNuxtModule<ModuleOptions>({
           // Backend specific variables that are safe to share.
           // We want them to be overridable like the other public keys (e.g NUXT_PUBLIC_CLERK_PROXY_URL)
           proxyUrl: options.proxyUrl,
-          apiUrl: 'https://api.clerk.com',
+          apiUrl: '',
           apiVersion: 'v1',
         },
       },

packages/nuxt/src/runtime/server/__tests__/clerkClient.test.ts

@@ -0,0 +1,94 @@
+import { vi } from 'vitest';
+
+// These globals are normally injected at build time by tsup.
+(globalThis as any).PACKAGE_NAME = '@clerk/nuxt';
+(globalThis as any).PACKAGE_VERSION = '0.0.0-test';
+
+vi.mock('#imports', () => {
+  return {
+    useRuntimeConfig: vi.fn(),
+  };
+});
+
+vi.mock('@clerk/backend', () => {
+  return {
+    createClerkClient: vi.fn().mockReturnValue({}),
+  };
+});
+
+import { createClerkClient } from '@clerk/backend';
+
+// @ts-expect-error: Nitro import. Handled by Nuxt.
+import { useRuntimeConfig } from '#imports';
+
+import { clerkClient } from '../clerkClient';
+
+const useRuntimeConfigMock = vi.mocked(useRuntimeConfig);
+const createClerkClientMock = vi.mocked(createClerkClient);
+
+function mockRuntimeConfig(overrides: { publishableKey?: string; apiUrl?: string } = {}) {
+  useRuntimeConfigMock.mockReturnValue({
+    public: {
+      clerk: {
+        publishableKey: overrides.publishableKey ?? 'pk_test_Y2xlcmsuY2xlcmsuY29tJA',
+        apiUrl: overrides.apiUrl ?? '',
+        apiVersion: 'v1',
+        proxyUrl: '',
+        domain: '',
+        isSatellite: false,
+        telemetry: {},
+      },
+    },
+    clerk: {
+      secretKey: 'sk_test_xxx',
+      machineSecretKey: '',
+      jwtKey: '',
+    },
+  } as any);
+}
+
+describe('clerkClient', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('derives staging API URL from staging publishable key', () => {
+    // pk_test_ + base64("safe-egret-46.clerk.accountsstage.dev$")
+    const stagingPk = 'pk_test_c2FmZS1lZ3JldC00Ni5jbGVyay5hY2NvdW50c3N0YWdlLmRldiQ';
+    mockRuntimeConfig({ publishableKey: stagingPk });
+
+    clerkClient({} as any);
+
+    expect(createClerkClientMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiUrl: 'https://api.clerkstage.dev',
+      }),
+    );
+  });
+
+  it('uses production API URL for production publishable key', () => {
+    const prodPk = 'pk_test_Y2xlcmsuY2xlcmsuY29tJA';
+    mockRuntimeConfig({ publishableKey: prodPk });
+
+    clerkClient({} as any);
+
+    expect(createClerkClientMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiUrl: 'https://api.clerk.com',
+      }),
+    );
+  });
+
+  it('prefers explicit apiUrl over derived value', () => {
+    const stagingPk = 'pk_test_c2FmZS1lZ3JldC00Ni5jbGVyay5hY2NvdW50c3N0YWdlLmRldiQ';
+    mockRuntimeConfig({ publishableKey: stagingPk, apiUrl: 'https://custom.api.example.com' });
+
+    clerkClient({} as any);
+
+    expect(createClerkClientMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        apiUrl: 'https://custom.api.example.com',
+      }),
+    );
+  });
+});

packages/nuxt/src/runtime/server/clerkClient.ts

@@ -1,4 +1,5 @@
 import { createClerkClient } from '@clerk/backend';
+import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
 import { isTruthy } from '@clerk/shared/underscore';
 import type { H3Event } from 'h3';
 
@@ -7,10 +8,12 @@ import { useRuntimeConfig } from '#imports';
 
 export function clerkClient(event: H3Event) {
   const runtimeConfig = useRuntimeConfig(event);
+  const publishableKey = runtimeConfig.public.clerk.publishableKey;
+  const apiUrl = runtimeConfig.public.clerk.apiUrl || apiUrlFromPublishableKey(publishableKey);
 
   return createClerkClient({
-    publishableKey: runtimeConfig.public.clerk.publishableKey,
-    apiUrl: runtimeConfig.public.clerk.apiUrl,
+    publishableKey,
+    apiUrl,
     apiVersion: runtimeConfig.public.clerk.apiVersion,
     proxyUrl: runtimeConfig.public.clerk.proxyUrl,
     domain: runtimeConfig.public.clerk.domain,