Clerk Changelog

After a little over a month in Beta, we're making our latest major release Generally Available. Core 2 represents a massive overhaul to the way Clerk works under the hood and ships with a bunch of goodies for you and your users. Going forward, whenever you install one of our Clerk packages, you'll be able to take full advantage of the latest Core 2 features.

We want to thank everyone who participated in the beta and helped us get to this point 💜.

Head to our Core 2 Upgrade Guides or try one of our Quickstarts to get started with Core 2 today!

Until recently, the Bot Protection feature was entirely invisible to end-users. While effective in most cases, occasionally real users were being wrongly identified as bots (aka. false positives) and were therefore blocked from signing up to the application, without having a way to rectify the error. To overcome this issue, users would have to reach out via support channels for remediation.

Clerk now expands the functionality of Bot Protection by offering more control over the widget, allowing your end-users to overcome such situations on their own. There are now two Bot Protection widget types:

1. Invisible: Render an invisible challenge if bot traffic is suspected. (This is what we had until now.)
2. Smart: Render an interactive challenge if bot traffic is suspected. Suspected users will have to click to the widget in order to prove they're not a bot.

For instances that had previously enabled Bot Protection, your settings are automatically set to Invisible as this was the previous default. In the near future, all new instances will default to Smart.

To configure your Bot Protection settings, head to the Attack Protection⁠ section of Clerk Dashboard and read more about Bot Protection.

SAML Enterprise Connections are now Generally Available

You may have heard this was coming when we shared our notice in February that SAML Enterprise Connections were exiting Beta. Well... today is the day. Thank you to all of the customers who participated in the Beta and helped harden this functionality 🎉.

But like Steve Jobs often said, there's one more thing...

IdP Initiated SSO is here

Along with the GA, we're also releasing IdP-initiated SSO. This means your customers can now use their IdP of choice (Google Workspace, Microsoft AD, Okta, etc) to initiate sign ins, instead of having to start at your app's Sign In views.

While this can be a major quality of life upgrade for your users who already use their IdP's for their other applications, it's important to weigh the risks of IdP-intiated SSO for your application.

If you think your users would be interested in this, have a peek at our IdP-initiated flow docs.

A few more things...

Apologies. I said one more thing but I guess I meant, a few more things. I got caught up in the moment 🙇.

In addition to the GA and the IdP-initiated feature release, we also made some quality-of-life improvements to the Dashboard when configuring Enterprise Connections. The new updates make it less error prone and more intuitive to provision the different providers, and improve the overall developer experience.

Alongside the GA we also released a few specific tutorials that cover setting up SAML Enterprise Connections for Azure, Google Workspace, and Okta.

If you haven't taken a look at Enterprise Connections⁠ in a bit, we encourage you to take another look!

Install the package

To get up and running with Clerk and Astro, start by installing the astro-clerk-auth and @astrojs/node packages:

npm i astro-clerk-auth @astrojs/node

Add environment variables

Before you start using the Clerk integration, you'll first need to set the following environment variables:

PUBLIC_ASTRO_APP_CLERK_PUBLISHABLE_KEY=<your-publishable-key>
CLERK_SECRET_KEY=<your-secret-key>

PUBLIC_ASTRO_APP_CLERK_SIGN_IN_URL=/sign-in
PUBLIC_ASTRO_APP_CLERK_SIGN_UP_URL=/sign-up

Extend the types

Update the env.d.ts file inside your Astro project:

/// <reference types="astro/client" />
/// <reference types="astro-clerk-auth/env" />

Add the Clerk integration

Open astro.config.mjs file and add the clerk() integration, and set the output to server:

import { defineConfig } from 'astro/config'
import node from '@astrojs/node'
import clerk from 'astro-clerk-auth'

export default defineConfig({
  integrations: [clerk()],
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
})

Use the middleware

This example showcases how to use the clerkMiddleware and the createRouteMatcher in Astro:

import { clerkMiddleware, createRouteMatcher } from 'astro-clerk-auth/server'

const isProtectedPage = createRouteMatcher(['/user(.*)'])

export const onRequest = clerkMiddleware((auth, context, next) => {
  if (isProtectedPage(context.request) && !auth().userId) {
    return auth().redirectToSignIn()
  }

  return next()
})

Use the components

The package exports the Clerk prebuilt UI components as Astro components and can be used anywhere inside the website:

---
import { SignedIn, SignedOut } from 'astro-clerk-auth/components/control'
import { UserButton, SignIn } from 'astro-clerk-auth/components/interactive'
---

<Layout title="Welcome to Astro + Clerk">
  <SignedIn>
    <UserButton />
  </SignedIn>

  <SignedOut>
    <SignIn routing="hash" />
  </SignedOut>
</Layout>

Congratulations, you have secured your Astro website with Clerk!

To learn more, check out the repo on GitHub⁠.

We've been working extremely hard to deliver (to you and your users) an improved overall experience with Clerk. In service of that, we've done some tidying up and are also rolling out some of our most highly requested SDK features.

Refreshed UI Components

Clerk SDKs included in the Core 2 release ship with improved design and UX on all of our UI components. Our new designs are the right starting point for any app. We continually strive to deliver a best-in-class collection of drop-in UI components that you can trust will get the job done for your users, so you can focus on building.

As always, if your app has custom needs, you can leverage our appearance prop, or use our hooks to fully customize your app's authentication experience.

New default middleware for Next.js

We've heard your feedback, and we've re-implemented our middleware helpers for Next.js. In Core 2, our middleware now defaults to not protecting any routes (previously it was the opposite). Going forward, you specify which routes you'd like to protect. You felt it made more sense to selectively configure your route protection, and we agree.

Additionally, the middleware bundle generated during build is now just 38kb instead of 150kb. This significantly reduces bundle size for better performance.

The new middleware is called clerkMiddleware, and you can read all about it in the docs⁠ and upgrade guide⁠. Here's an example of how you'd protect all routes under /dashboard:

// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)'])

export default clerkMiddleware((auth, request) => {
  if (isProtectedRoute(request)) auth().protect()
})

export const config = {
  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
}

No more white flash for your users

Previously, we went to great lengths behind the scenes to synchronize your app's auth state client-side. This approach (unaffectionately called Interstitial internally at Clerk) often led to a sub-optimal experience where end users were shown a brief white flash while we sorted through the exchange.

Over the last few months, we've fully re-imagined our underlying session syncing logic (now affectionately called 🤝 Handshake internally) to no longer require client-side Javascript. The end result? 2x-5x faster execution (depending on the environment, your device, and the network) and lower latency for your end-users.

No more 401s. No more white flash. No more infinite redirects. A considerably snappier experience.

A whole lot of house cleaning

As Clerk has matured, so have our SDKs – and leading into v4 we were carrying around a considerable amount of technical debt. This release, Core 2, drops quite a bit of that debt, by way of simplifying internal logic and dropping previously deprecated functionality.

As an example, SDKs included in Core 2 will require you to use at least Node.js 18.17.0, React 18, and Next.js 13.0.4 or later. This allowed us to remove polyfills, compatibility layers, and complex logic that made it easier to introduce bugs.

Read the Core 2 migration guide⁠ to get all the details.

A CLI tool to help you upgrade

We know dealing with any major release for a piece of your underlying infrastructure, like auth, can be challenging. You just want to get back to building the core functionality of your app – we get it.

To aid you in this upgrade, we've built a CLI tool called @clerk/upgrade⁠ that scans your codebase and guides you step-by-step in upgrading to Core 2. No upgrade is ever perfect, but we're committed to getting you on to the latest and greatest, and back to shipping 🚀

Get started with Core 2 Beta

Want to get started with your upgrade process? Head over to our Core 2 migration guide⁠, or you can start fresh with one of our quickstart guides⁠. If you need help, please contact support or join the Clerk Community on Discord⁠.

This release is still a beta and we do not recommend deploying it to production, but we do expect a stable release soon. Your feedback⁠ during the beta phase is enormously valuable for ensuring a smooth, stable rollout.

Happy coding ✌️

If you're one of the many businesses that have contacted us about GDPR compliance, you may be pleased with our latest announcement...

Clerk is now self-certified under the Data Privacy Framework (DPF)⁠.

What does that mean? Well, I thought you'd never ask... The DPF website describes⁠ it as:

If that's too many acronyms for you, you're not alone. Compliance is complicated. In plainer terms, certification under the DPF is a way for a US business like Clerk to transfer and store an EU citizen's personal data in a way that is in accordance with GDPR.

At Clerk, we're on a mission to make compliance more accessible for you and your customers. And while the governing regulations are continually shifting under our feet; by self-certifying under the DPF, we're following the path of some of many other leading US-based SaaS businesses (like Stripe⁠, Github⁠, and Auth0⁠). We look at this as an important milestone in our compliance story, and we expect to continue to make more strides in this area as Clerk continues to grow.

If you're the type, have a peek at our updated Privacy Policy and the associated Data Privacy Framework Notice.

Another privacy related note...

In the past, it had been popular to display a user's full name and profile picture while signing in as a means to help drive better conversion. However, this practice is no longer recommended due to the rise of privacy regulations like GDPR and CCPA. Going forward we've made a change to our API to limit the amount of data we return before a user is signed in. While limiting this data will be default going forward, pre-existing instances have the ability to opt-in to this recommended security measure by heading to our Attack Protection⁠ page in the Clerk Dashboard.