clerk · dstaley · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/.changeset/migrate-build-tooling-tsdown-ts6.md b/.changeset/migrate-build-tooling-tsdown-ts6.md
@@ -0,0 +1,22 @@
+---
+'@clerk/tanstack-react-start': patch
+'@clerk/chrome-extension': patch
+'@clerk/expo-passkeys': patch
+'@clerk/react-router': patch
+'@clerk/localizations': patch
+'@clerk/express': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/testing': patch
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/astro': patch
+'@clerk/expo': patch
+'@clerk/hono': patch
+'@clerk/nuxt': patch
+'@clerk/react': patch
+'@clerk/vue': patch
+'@clerk/ui': patch
+---
+
+Migrate the build pipeline to tsdown and TypeScript 6.0. This is an internal tooling change with no intended changes to the public API or runtime behavior.
diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs
@@ -82,7 +82,10 @@ const LINK_REPLACEMENTS = [
   ['enterprise-account-connection', '/docs/reference/backend/types/backend-enterprise-account-connection'],
   ['enterprise-connection', '/docs/reference/backend/types/backend-enterprise-connection'],
   ['enterprise-connection-oauth-config', '/docs/reference/backend/types/backend-enterprise-connection-oauth-config'],
-  ['enterprise-connection-saml-connection', '/docs/reference/backend/types/backend-enterprise-connection-saml-connection'],
+  [
+    'enterprise-connection-saml-connection',
+    '/docs/reference/backend/types/backend-enterprise-connection-saml-connection',
+  ],
   ['external-account', '/docs/reference/backend/types/backend-external-account'],
   ['phone-number', '/docs/reference/backend/types/backend-phone-number'],
   ['saml-account', '/docs/reference/backend/types/backend-saml-account'],

diff --git a/integration/templates/astro-hybrid/astro.config.mjs b/integration/templates/astro-hybrid/astro.config.mjs
@@ -20,4 +20,11 @@ export default defineConfig({
   server: {
     port: process.env.PORT ? Number(process.env.PORT) : undefined,
   },
+  vite: {
+    build: {
+      rollupOptions: {
+        external: ['cloudflare:workers'],
+      },
+    },
+  },
 });
diff --git a/integration/templates/astro-node/astro.config.mjs b/integration/templates/astro-node/astro.config.mjs
@@ -24,4 +24,11 @@ export default defineConfig({
   server: {
     port: process.env.PORT ? Number(process.env.PORT) : undefined,
   },
+  vite: {
+    build: {
+      rollupOptions: {
+        external: ['cloudflare:workers'],
+      },
+    },
+  },
 });
diff --git a/package.json b/package.json
@@ -146,6 +146,7 @@
     "typedoc-plugin-replace-text": "4.2.0",
     "typescript": "catalog:repo",
     "typescript-eslint": "8.58.0",
+    "unrun": "0.2.39",
     "uuid": "8.3.2",
     "vitest": "3.2.4",
     "zx": "catalog:repo"

diff --git a/packages/astro/package.json b/packages/astro/package.json
@@ -77,10 +77,10 @@
     "types.ts"
   ],
   "scripts": {
-    "build": "tsup --onSuccess \"pnpm build:declarations\" && pnpm copy:components",
-    "build:declarations": "tsc -p tsconfig.declarations.json",
+    "build": "tsdown --onSuccess \"pnpm build:dts\" && pnpm copy:components",
+    "build:dts": "tsc --emitDeclarationOnly --declaration",
     "copy:components": "rm -rf ./components && mkdir -p ./components/ && cp  -r ./src/astro-components/* ./components/ && cp ./src/types.ts ./",
-    "dev": "tsup --watch",
+    "dev": "tsdown --watch",
     "dev:pub": "pnpm dev -- --env.publish",
     "format": "node ../../scripts/format-package.mjs",
     "format:check": "node ../../scripts/format-package.mjs --check",

diff --git a/packages/astro/tsup.config.ts → packages/astro/tsdown.config.mts b/packages/astro/tsup.config.ts → packages/astro/tsdown.config.mts
@@ -1,7 +1,6 @@
-import { defineConfig } from 'tsup';
+import { defineConfig } from 'tsdown';
 
-// @ts-ignore
-import { name, version } from './package.json';
+import pkgJson from './package.json' with { type: 'json' };
 
 export default defineConfig(overrideOptions => {
   const shouldPublish = !!overrideOptions.env?.publish;
@@ -23,12 +22,21 @@ export default defineConfig(overrideOptions => {
     minify: false,
     onSuccess: shouldPublish ? 'pnpm build:declarations && pkglab pub --ping' : 'pnpm build:declarations',
     define: {
-      PACKAGE_NAME: `"${name}"`,
-      PACKAGE_VERSION: `"${version}"`,
+      PACKAGE_NAME: `"${pkgJson.name}"`,
+      PACKAGE_VERSION: `"${pkgJson.version}"`,
     },
-    bundle: true,
     sourcemap: true,
     format: ['esm'],
-    external: ['astro', 'react', 'react-dom', 'node:async_hooks', '#async-local-storage', 'astro:transitions/client'],
+    fixedExtension: false,
+    external: [
+      'astro',
+      'react',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+      'react-dom',
+      'node:async_hooks',
+      '#async-local-storage',
+      'astro:transitions/client',
+    ],
   };
 });
diff --git a/packages/backend/src/api/endpoints/JwtTemplatesApi.ts b/packages/backend/src/api/endpoints/JwtTemplatesApi.ts
@@ -1,6 +1,6 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
-import { joinPaths } from 'src/util/path';
 
+import { joinPaths } from '../../util/path';
 import type { DeletedObject, JwtTemplate } from '../resources';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';

diff --git a/packages/backend/src/api/endpoints/WaitlistEntryApi.ts b/packages/backend/src/api/endpoints/WaitlistEntryApi.ts
@@ -1,6 +1,6 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
-import { joinPaths } from 'src/util/path';
 
+import { joinPaths } from '../../util/path';
 import type { DeletedObject } from '../resources/DeletedObject';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { WaitlistEntryStatus } from '../resources/Enums';

diff --git a/packages/backend/src/jwt/cryptoKeys.ts b/packages/backend/src/jwt/cryptoKeys.ts
@@ -3,7 +3,7 @@ import { isomorphicAtob } from '@clerk/shared/isomorphicAtob';
 import { runtime } from '../runtime';
 
 // https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#pkcs_8_import
-function pemToBuffer(secret: string): ArrayBuffer {
+function pemToBuffer(secret: string): Uint8Array<ArrayBuffer> {
   const trimmed = secret
     .replace(/-----BEGIN.*?-----/g, '')
     .replace(/-----END.*?-----/g, '')

diff --git a/packages/backend/src/jwt/index.ts b/packages/backend/src/jwt/index.ts
@@ -1,5 +1,8 @@
+import type { Jwt, JwtPayload } from '@clerk/shared/types';
+
 import { withLegacyReturn, withLegacySyncReturn } from './legacyReturn';
 import { signJwt as _signJwt } from './signJwt';
+import type { VerifyJwtOptions } from './verifyJwt';
 import { decodeJwt as _decodeJwt, hasValidSignature as _hasValidSignature, verifyJwt as _verifyJwt } from './verifyJwt';
 
 export type { VerifyJwtOptions } from './verifyJwt';
@@ -8,8 +11,15 @@ export type { SignJwtOptions } from './signJwt';
 // Introduce compatibility layer to avoid more breaking changes
 // TODO(dimkl): This (probably be drop in the next major version)
 
-export const verifyJwt = withLegacyReturn(_verifyJwt);
-export const decodeJwt = withLegacySyncReturn(_decodeJwt);
+// These exports wrap their implementations through `withLegacyReturn`, which produces an
+// inferred return type. Without an explicit annotation, `tsc`'s declaration emit resolves
+// `Jwt`/`JwtPayload` to their declaration site inside `@clerk/shared`'s bundled (and
+// export-blocked) `_chunks/*` output, leaving consumers with an unresolvable module
+// specifier. Annotating the public types pins the emitted reference to `@clerk/shared/types`.
+export const verifyJwt: (token: string, options: VerifyJwtOptions) => Promise<JwtPayload> =
+  withLegacyReturn(_verifyJwt);
+export const decodeJwt: (token: string) => Jwt = withLegacySyncReturn(_decodeJwt);
 
 export const signJwt = withLegacyReturn(_signJwt);
-export const hasValidSignature = withLegacyReturn(_hasValidSignature);
+export const hasValidSignature: (jwt: Jwt, key: JsonWebKey | string) => Promise<boolean> =
+  withLegacyReturn(_hasValidSignature);
diff --git a/packages/backend/src/jwt/verifyJwt.ts b/packages/backend/src/jwt/verifyJwt.ts
@@ -28,7 +28,12 @@ export async function hasValidSignature(jwt: Jwt, key: JsonWebKey | string): Pro
   try {
     const cryptoKey = await importKey(key, algorithm, 'verify');
 
-    const verified = await runtime.crypto.subtle.verify(algorithm.name, cryptoKey, signature, data);
+    const verified = await runtime.crypto.subtle.verify(
+      algorithm.name,
+      cryptoKey,
+      signature as Uint8Array<ArrayBuffer>,
+      data,
+    );
     return { data: verified };
   } catch (error) {
     return {

diff --git a/packages/backend/src/webhooks.ts b/packages/backend/src/webhooks.ts
@@ -1,8 +1,8 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
-import { errorThrower } from 'src/util/shared';
 import { Webhook } from 'standardwebhooks';
 
 import type { WebhookEvent } from './api/resources/Webhooks';
+import { errorThrower } from './util/shared';
 
 /**
  * @inline

diff --git a/packages/backend/tsconfig.json b/packages/backend/tsconfig.json
@@ -1,7 +1,6 @@
 {
   "compilerOptions": {
     "allowSyntheticDefaultImports": true,
-    "baseUrl": ".",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "importHelpers": true,

diff --git a/packages/chrome-extension/tsconfig.json b/packages/chrome-extension/tsconfig.json
@@ -17,7 +17,8 @@
     "declaration": true,
     "declarationDir": "dist/types",
     "declarationMap": true,
-    "emitDeclarationOnly": true
+    "emitDeclarationOnly": true,
+    "rootDir": "./src"
   },
   "include": ["src"]
 }
diff --git a/packages/clerk-js/bundlewatch.config.json b/packages/clerk-js/bundlewatch.config.json
@@ -7,7 +7,7 @@
     { "path": "./dist/clerk.native.js", "maxSize": "70KB" },
     { "path": "./dist/vendors*.js", "maxSize": "7KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
-    { "path": "./dist/base-account-sdk*.js", "maxSize": "203KB" },
+    { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },
     { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },
     { "path": "./dist/query-core-vendors*.js", "maxSize": "11KB" },
     { "path": "./dist/zxcvbn-ts-core*.js", "maxSize": "12KB" },

diff --git a/packages/clerk-js/sandbox/app.ts b/packages/clerk-js/sandbox/app.ts
@@ -1,5 +1,5 @@
 import { PageMocking, type MockScenario } from '@clerk/msw';
-import * as l from '../../localizations';
+import * as l from '../../localizations/src';
 import { dark, neobrutalism, shadcn, shadesOfPurple } from '../../ui/src/themes';
 import type { Clerk as ClerkType } from '../';
 import { initCommandPalette } from './cmdk';

diff --git a/packages/clerk-js/tsconfig.json b/packages/clerk-js/tsconfig.json
@@ -7,7 +7,7 @@
     "isolatedModules": true,
     "jsx": "react-jsx",
     "jsxImportSource": "@emotion/react",
-    "lib": ["dom", "dom.iterable", "es2021.intl"],
+    "lib": ["dom", "dom.iterable", "es2020", "es2021.intl"],
     "module": "esnext",
     "moduleResolution": "Bundler",
     "noEmit": true,
@@ -22,7 +22,9 @@
     "useUnknownInCatchVariables": false,
     "paths": {
       "@/*": ["./src/*"]
-    }
+    },
+    "rootDir": "./src",
+    "types": ["@rspack/core/module", "cloudflare-turnstile"]
   },
   "include": ["src", "vitest.config.mts", "vitest.setup.mts", "../shared/internal/clerk-js/componentGuards.ts"]
 }
diff --git a/packages/expo-passkeys/src/ClerkExpoPasskeys.types.ts b/packages/expo-passkeys/src/ClerkExpoPasskeys.types.ts
@@ -43,50 +43,14 @@ export type SerializedPublicKeyCredentialRequestOptions = Omit<
   challenge: string;
 };
 
-// The return type from the "get" native module.
-export interface AuthenticationResponseJSON {
-  id: string;
-  rawId: string;
-  response: AuthenticatorAssertionResponseJSON;
-  authenticatorAttachment?: AuthenticatorAttachment;
-  clientExtensionResults: AuthenticationExtensionsClientOutputs;
-  type: PublicKeyCredentialType;
-}
-
 // The serialized response of the native module "create" response to be send back to clerk
 export type PublicKeyCredentialWithAuthenticatorAttestationResponse =
   ClerkPublicKeyCredentialWithAuthenticatorAttestationResponse & {
     toJSON: () => any;
   };
 
-interface AuthenticatorAssertionResponseJSON {
-  clientDataJSON: string;
-  authenticatorData: string;
-  signature: string;
-  userHandle?: string;
-}
-
 // The serialized response of the native module "get" response to be send back to clerk
 export type PublicKeyCredentialWithAuthenticatorAssertionResponse =
   ClerkPublicKeyCredentialWithAuthenticatorAssertionResponse & {
     toJSON: () => any;
   };
-
-interface AuthenticatorAttestationResponseJSON {
-  clientDataJSON: string;
-  attestationObject: string;
-  authenticatorData?: string;
-  transports?: AuthenticatorTransportFuture[];
-  publicKeyAlgorithm?: COSEAlgorithmIdentifier;
-  publicKey?: string;
-}
-
-// The type is returned from from native module "create" response
-export interface RegistrationResponseJSON {
-  id: string;
-  rawId: string;
-  response: AuthenticatorAttestationResponseJSON;
-  authenticatorAttachment?: AuthenticatorAttachment;
-  clientExtensionResults: AuthenticationExtensionsClientOutputs;
-  type: PublicKeyCredentialType;
-}
diff --git a/packages/expo-passkeys/src/index.ts b/packages/expo-passkeys/src/index.ts
@@ -1,13 +1,11 @@
 import { Platform } from 'react-native';
 
 import type {
-  AuthenticationResponseJSON,
   CredentialReturn,
   PublicKeyCredentialCreationOptionsWithoutExtensions,
   PublicKeyCredentialRequestOptionsWithoutExtensions,
   PublicKeyCredentialWithAuthenticatorAssertionResponse,
   PublicKeyCredentialWithAuthenticatorAttestationResponse,
-  RegistrationResponseJSON,
   SerializedPublicKeyCredentialCreationOptions,
   SerializedPublicKeyCredentialRequestOptions,
 } from './ClerkExpoPasskeys.types';

diff --git a/packages/expo-passkeys/tsconfig.json b/packages/expo-passkeys/tsconfig.json
@@ -1,7 +1,6 @@
 {
   "compilerOptions": {
     "allowJs": true,
-    "baseUrl": ".",
     "declaration": true,
     "declarationMap": false,
     "esModuleInterop": true,
@@ -20,7 +19,9 @@
     "skipLibCheck": true,
     "sourceMap": false,
     "strict": true,
-    "target": "ES2019"
+    "target": "ES2019",
+    "types": ["node"],
+    "rootDir": "./src"
   },
   "include": ["src"]
 }
diff --git a/packages/expo/package.json b/packages/expo/package.json
@@ -101,10 +101,10 @@
     "app.plugin.d.ts"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "build:declarations": "tsc -p tsconfig.declarations.json",
     "clean": "rimraf ./dist",
-    "dev": "tsup --watch",
+    "dev": "tsdown --watch",
     "dev:pub": "pnpm dev -- --env.publish",
     "format": "node ../../scripts/format-package.mjs",
     "format:check": "node ../../scripts/format-package.mjs --check",

diff --git a/packages/expo/src/cache/index.ts b/packages/expo/src/cache/index.ts
@@ -1,4 +1,4 @@
-export { TokenCache } from './types';
+export type { TokenCache } from './types';
 
 export { MemoryTokenCache } from './MemoryTokenCache';
 export { ClientResourceCache, EnvironmentResourceCache, SessionJWTCache } from './ResourceCache';

diff --git a/packages/expo/src/polyfills/base64Polyfill.ts b/packages/expo/src/polyfills/base64Polyfill.ts
@@ -3,11 +3,11 @@ import { decode, encode } from 'base-64';
 import { isHermes } from '../utils';
 
 // See Default Expo 51 engine Hermes' issue: https://github.com/facebook/hermes/issues/1379
-if (!global.btoa || isHermes()) {
-  global.btoa = encode;
+if (!globalThis.btoa || isHermes()) {
+  globalThis.btoa = encode;
 }
 
 // See Default Expo 51 engine Hermes' issue: https://github.com/facebook/hermes/issues/1379
-if (!global.atob || isHermes()) {
-  global.atob = decode;
+if (!globalThis.atob || isHermes()) {
+  globalThis.atob = decode;
 }
diff --git a/packages/expo/tsconfig.json b/packages/expo/tsconfig.json
@@ -1,8 +1,7 @@
 {
   "compilerOptions": {
     "outDir": "dist",
-    "baseUrl": ".",
-    "lib": ["es6", "dom"],
+    "lib": ["es2019", "dom"],
     "jsx": "react-jsx",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",