@clerk/astro
4.1.27 · 18 Nov 2026MIT46.5k / weekRepositoryHomepagenpmAtom feed
3.4.20 is the newest release of 3.x.
In short
5 breaking2 removed6 new3 fixed2 changed2 internal
- Breaking
Require Node.js 20.9.0 in all packages
- Breaking
Remove deprecated
asprop from unstyled button components (SignInButton,SignUpButton,SignOutButton,CheckoutButton,PlanDetailsButton,SubscriptionDetailsButton). Use theasChildprop with a custom element in the default slot instead. - Breaking
Remove
clerkJSUrl,clerkJSVersion,clerkUIUrl, andclerkUIVersionprops from all SDKs. To pin a specific version of@clerk/clerk-js, import theClerkconstructor from@clerk/clerk-jsand pass it toClerkProvidervia theClerkprop. To pin a specific version of@clerk/ui, importuifrom@clerk/uiand pass it via theuiprop. This bundles the modules directly with your application instead of loading them from the CDN. - Breaking
Introduce
<Show when={...}>as the cross-framework authorization control component and remove<Protect>,<SignedIn>, and<SignedOut>in favor of<Show>. - Breaking
Changed environment variable resolution order in
getContextEnvVar()to preferprocess.envoverimport.meta.env. Runtime environment variables (e.g., set in the Node.js adapter) now take precedence over build-time values statically replaced by Vite. This ensures that environment variables set at runtime behave as expected when deploying with the Astro Node adapter or similar runtime environments. - Removed
Removed deprecated billing-related props (
__unstable_manageBillingUrl,__unstable_manageBillingLabel,__unstable_manageBillingMembersLimit) andexperimental__forceOauthFirst - Removed
Remove
clerkJSVariantoption and headless bundle. UseprefetchUI={false}instead.
Security
2 advisories affect 3.0.0; 3.0.18 fixes them
- CriticalOfficial Clerk JavaScript SDKs: Middleware-based route protection bypassGHSA-vqx2-fgx2-5wq9 · 16 Apr 2026Fixed in 3.0.15
- HighClerk has an authorization bypass when combining organization, billing, or reverification checksGHSA-w24r-5266-9c3c · 30 Apr 2026Fixed in 3.0.18
Release note
Major Changes
- Breaking
Align experimental/unstable prefixes to use consistent naming:
Renamed all
__unstable_*methods to__internal_*(for internal APIs)Renamed all
experimental__*andexperimental_*methods to__experimental_*(for beta features)Removed deprecated billing-related props (
__unstable_manageBillingUrl,__unstable_manageBillingLabel,__unstable_manageBillingMembersLimit) andexperimental__forceOauthFirst
- Breaking
Require Node.js 20.9.0 in all packages
- Breaking
Remove deprecated
asprop from unstyled button components (SignInButton,SignUpButton,SignOutButton,CheckoutButton,PlanDetailsButton,SubscriptionDetailsButton). Use theasChildprop with a custom element in the default slot instead.Before:
<SignInButton as='a' href='/sign-in' > Sign in </SignInButton>
After:
<SignInButton asChild> <a href='/sign-in'>Sign in</a> </SignInButton>
- Breaking
Remove
clerkJSUrl,clerkJSVersion,clerkUIUrl, andclerkUIVersionprops from all SDKs. To pin a specific version of@clerk/clerk-js, import theClerkconstructor from@clerk/clerk-jsand pass it toClerkProvidervia theClerkprop. To pin a specific version of@clerk/ui, importuifrom@clerk/uiand pass it via theuiprop. This bundles the modules directly with your application instead of loading them from the CDN. - Breaking
Introduce
<Show when={...}>as the cross-framework authorization control component and remove<Protect>,<SignedIn>, and<SignedOut>in favor of<Show>. - Breaking
Changed environment variable resolution order in
getContextEnvVar()to preferprocess.envoverimport.meta.env. Runtime environment variables (e.g., set in the Node.js adapter) now take precedence over build-time values statically replaced by Vite. This ensures that environment variables set at runtime behave as expected when deploying with the Astro Node adapter or similar runtime environments.
Minor Changes
- Removed
Remove
clerkJSVariantoption and headless bundle. UseprefetchUI={false}instead. Introduce Keyless quickstart for Astro. This allows the Clerk SDK to be used without having to sign up and paste your keys manually.
Add
uiprop toClerkProviderfor passing@clerk/uiAdd standalone
getToken()function for retrieving session tokens outside of framework component trees.This function is safe to call from anywhere in the browser, such as API interceptors, data fetching layers (e.g., React Query, SWR), or vanilla JavaScript code. It automatically waits for Clerk to initialize before returning the token.
import { getToken } from '@clerk/nextjs'; // or any framework package
// Example: Axios interceptor
axios.interceptors.request.use(async (config) => {
const token = await getToken();
if (token) {
config.headers.Authorization =Bearer ${token};
}
return config;
});Add
/typessubpath export to re-export types from@clerk/shared/typesalong with SDK-specific types. This allows importing Clerk types directly from the SDK package (e.g.,import type { UserResource } from '@clerk/react/types') without needing to install@clerk/typesas a separate dependency.Introduce
<UNSAFE_PortalProvider>component which allows you to specify a custom container for Clerk floating UI elements (popovers, modals, tooltips, etc.) that use portals. Only Clerk components within the provider will be affected, components outside the provider will continue to use the default document.body for portals.This is particularly useful when using Clerk components inside external UI libraries like Radix Dialog or React Aria Components, where portaled elements need to render within the dialog's container to remain interact-able.
'use client'; import { useRef } from 'react'; import * as Dialog from '@radix-ui/react-dialog'; import { UNSAFE_PortalProvider, UserButton } from '@clerk/nextjs'; export function UserDialog() { const containerRef = useRef<HTMLDivElement>(null); return ( <Dialog.Root> <Dialog.Trigger>Open Dialog</Dialog.Trigger> <Dialog.Portal> <Dialog.Overlay /> <Dialog.Content ref={containerRef}> <UNSAFE_PortalProvider getContainer={() => containerRef.current}> <UserButton /> </UNSAFE_PortalProvider> </Dialog.Content> </Dialog.Portal> </Dialog.Root> ); }
Patch Changes
Rename dev browser APIs to remove JWT terminology. The dev browser identifier is now a generic ID, so internal naming has been updated to reflect this. No runtime behavior changes.
Wire
clerkUIVersionoption through all framework packagesFix compatibility with Astro v6 Cloudflare adapter by using
cloudflare:workersenv whenlocals.runtime.envis unavailableAdd
satelliteAutoSyncoption to optimize satellite app handshake behaviorSatellite apps currently trigger a handshake redirect on every first page load, even when no cookies exist. This creates unnecessary redirects to the primary domain for apps where most users aren't authenticated.
New option:
satelliteAutoSync(default:false)When
false(default): Skip automatic handshake if no session cookies exist, only trigger after explicit sign-in actionWhen
true: Satellite apps automatically trigger handshake on first load (previous behavior)
New query parameter:
__clerk_sync__clerk_sync=1(NeedsSync): Triggers handshake after returning from primary sign-in__clerk_sync=2(Completed): Prevents re-sync loop after handshake completes
Backwards compatible: Still reads legacy
__clerk_synced=trueparameter.SSR redirect fix: Server-side redirects (e.g.,
redirectToSignIn()from middleware) now correctly add__clerk_sync=1to the return URL for satellite apps. This ensures the handshake is triggered when the user returns from sign-in on the primary domain.CSR redirect fix: Client-side redirects now add
__clerk_sync=1to all redirect URL variants (forceRedirectUrl,fallbackRedirectUrl) for satellite apps, not just the defaultredirectUrl.
Usage
SSR (Next.js Middleware)
```typescript
import { clerkMiddleware } from '@clerk/nextjs/server';
export default clerkMiddleware({
isSatellite: true,
domain: 'satellite.example.com',
signInUrl: 'https://primary.example.com/sign-in',
// Set to true to automatically sync auth state on first load
satelliteAutoSync: true,
});
```SSR (TanStack Start)
```typescript
import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
export default clerkMiddleware({
isSatellite: true,
domain: 'satellite.example.com',
signInUrl: 'https://primary.example.com/sign-in',
// Set to true to automatically sync auth state on first load
satelliteAutoSync: true,
});
```CSR (ClerkProvider)
```tsx
<ClerkProvider
publishableKey='pk_...'
isSatellite={true}
domain='satellite.example.com'
signInUrl='https://primary.example.com/sign-in'
// Set to true to automatically sync auth state on first load
satelliteAutoSync={true}
>
{children}
</ClerkProvider>
```SSR (TanStack Start with callback)
```typescript
import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
// Options callback - receives context object, returns options
export default clerkMiddleware(({ url }) => ({
isSatellite: true,
domain: 'satellite.example.com',
signInUrl: 'https://primary.example.com/sign-in',
satelliteAutoSync: url.pathname.startsWith('/dashboard'),
}));
```Migration Guide
Behavior change: satelliteAutoSync defaults to false
Previously, satellite apps would automatically trigger a handshake redirect on every first page load to sync authentication state with the primary domain—even when no session cookies existed. This caused unnecessary redirects to the primary domain for users who weren't authenticated.
The new default (`satelliteAutoSync: false`) provides a better experience for end users. Performance-wise, the satellite app can be shown immediately without attempting to sync state first, which is the right behavior for most use cases.
**To preserve the previous behavior** where visiting a satellite while already signed in on the primary domain automatically syncs your session, set `satelliteAutoSync: true`:
```typescript
export default clerkMiddleware({
isSatellite: true,
domain: 'satellite.example.com',
signInUrl: 'https://primary.example.com/sign-in',
satelliteAutoSync: true, // Opt-in to automatic sync on first load
});
```TanStack Start: Function props to options callback
The `clerkMiddleware` function no longer accepts individual props as functions. If you were using the function form for props like `domain`, `proxyUrl`, or `isSatellite`, migrate to the options callback pattern.
**Before (prop function form - no longer supported):**
```typescript
import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
export default clerkMiddleware({
isSatellite: true,
// ❌ Function form for individual props no longer works
domain: url => url.hostname,
});
```
**After (options callback form):**
```typescript
import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
// ✅ Wrap entire options in a callback function
export default clerkMiddleware(({ url }) => ({
isSatellite: true,
domain: url.hostname,
}));
```
The callback receives a context object with the `url` property (a `URL` instance) and can return options synchronously or as a Promise for async configuration.- Breaking
Updated dependencies:
@clerk/shared@4.0.0
@clerk/backend@3.0.0
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.