feat(astro): Remove createRouteMatcher and support Astro 7

.changeset/floppy-buckets-help.md

@@ -0,0 +1,5 @@
+---
+"@clerk/astro": major
+---
+
+Add support for Astro 7 and drop support for Astro 4. If you are still on Astro 4, follow the [Astro upgrade guide](https://docs.astro.build/en/guides/upgrade-to/v6/) to upgrade your project before updating `@clerk/astro`.

.changeset/major-astro-remove-route-matcher.md

@@ -0,0 +1,43 @@
+---
+'@clerk/astro': major
+---
+
+Remove `createRouteMatcher` from `@clerk/astro/server`. Use resource-based auth checks instead: move auth checks into each Astro page, API route, or server-side handler that accesses protected data. Middleware-based auth checks rely on path matching, which can diverge from how Astro routes requests and leave protected resources reachable.
+
+```ts
+import type { APIRoute } from 'astro';
+
+export const GET: APIRoute = ({ locals }) => {
+  const { userId } = locals.auth();
+
+  if (!userId) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  return Response.json({ userId });
+};
+```
+
+If you want to hand this work to a coding agent, use this migration prompt:
+
+```md
+Migrate my Astro project away from Clerk's removed `createRouteMatcher` API.
+
+1. Open `src/middleware.ts` (or `src/middleware.js`) and find every matcher created
+   with `createRouteMatcher` from `@clerk/astro/server`, along with the middleware
+   logic that uses it (returning 401s, calling `auth().redirectToSignIn()`, etc.).
+2. For every route those matchers protected, move the auth check into the resource itself:
+   - In `.astro` pages, add this to the frontmatter:
+     const { userId, redirectToSignIn } = Astro.locals.auth();
+     if (!userId) return redirectToSignIn();
+   - In API routes and server handlers, add this at the top of the handler:
+     const { userId } = locals.auth();
+     if (!userId) return new Response('Unauthorized', { status: 401 });
+   - Keep any role or permission checks (`auth().has(...)`) with the resource as well.
+3. Remove the `createRouteMatcher` import and calls from the middleware. Keep
+   `clerkMiddleware()` itself. Middleware logic unrelated to auth protection
+   (locale redirects, headers, etc.) may stay, using plain `URL`/pathname checks.
+4. Make sure every page and endpoint previously covered by a matcher pattern
+   (including glob patterns like `/dashboard(.*)`) now has its own check, then
+   verify the project builds.
+```

integration/templates/astro-node/astro.config.mjs

@@ -3,8 +3,6 @@ import node from '@astrojs/node';
 import clerk from '@clerk/astro';
 import react from '@astrojs/react';
 
-import tailwind from '@astrojs/tailwind';
-
 export default defineConfig({
   output: 'server',
   adapter: node({
@@ -19,7 +17,6 @@ export default defineConfig({
       },
     }),
     react(),
-    tailwind(),
   ],
   server: {
     port: process.env.PORT ? Number(process.env.PORT) : undefined,

integration/templates/astro-node/package.json

@@ -10,16 +10,14 @@
     "start": "astro dev --port $PORT"
   },
   "dependencies": {
-    "@astrojs/check": "^0.9.4",
-    "@astrojs/node": "^9.0.0",
-    "@astrojs/react": "^4.0.0",
-    "@astrojs/tailwind": "^5.1.3",
+    "@astrojs/check": "^0.9.9",
+    "@astrojs/node": "^11.0.0",
+    "@astrojs/react": "^6.0.0",
     "@types/react": "18.3.7",
     "@types/react-dom": "18.3.0",
-    "astro": "^5.15.9",
+    "astro": "^7.0.2",
     "react": "18.3.1",
     "react-dom": "18.3.1",
-    "tailwindcss": "^3.4.17",
     "typescript": "^5.7.3"
   }
 }

integration/templates/astro-node/src/middleware.ts

@@ -1,35 +1,9 @@
-import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server';
-
-const unautorized = () =>
-  new Response(JSON.stringify({ error: 'unathorized access' }), {
-    status: 401,
-  });
-
-/**
- * 3. Support handler
- */
-const isProtectedPage = createRouteMatcher(['/user(.*)', '/discover(.*)']);
-
-const isProtectedApiRoute = createRouteMatcher(['/api/protected(.*)']);
+import { clerkMiddleware } from '@clerk/astro/server';
 
 export const onRequest = clerkMiddleware((auth, context, next) => {
   const requestURL = new URL(context.request.url);
-  if (['/sign-in', '/', '/sign-up'].includes(requestURL.pathname)) {
-    return next();
-  }
-
-  if (isProtectedApiRoute(context.request) && !auth().userId) {
-    return unautorized();
-  }
-
-  if (isProtectedPage(context.request) && !auth().userId) {
-    return auth().redirectToSignIn();
-  }
 
-  if (!auth().orgId && requestURL.pathname !== '/discover' && requestURL.pathname === '/organization') {
-    if (!auth().userId) {
-      return next();
-    }
+  if (requestURL.pathname === '/organization' && auth().userId && !auth().orgId) {
     const searchParams = new URLSearchParams({
       redirectUrl: requestURL.href,
     });

integration/templates/astro-node/src/pages/api/protected/current-org.ts

@@ -1,14 +1,13 @@
 import type { APIRoute } from 'astro';
 import { clerkClient } from '@clerk/astro/server';
 
-const empty = () => new Response(null);
-
 export const GET: APIRoute = async context => {
   const { locals } = context;
   const { userId, orgId } = locals.auth();
   if (!userId) {
-    // We are handling this at the middleware level
-    return empty();
+    return new Response(JSON.stringify({ error: 'unauthorized access' }), {
+      status: 401,
+    });
   }
 
   if (!orgId) {

integration/templates/astro-node/src/pages/api/protected/only-admin.ts

@@ -5,6 +5,12 @@ export const GET: APIRoute = async context => {
   const { locals } = context;
   const { auth } = locals;
 
+  if (!auth().userId) {
+    return new Response(JSON.stringify({ error: 'unauthorized access' }), {
+      status: 401,
+    });
+  }
+
   if (auth().has({ role: 'org:admin' })) {
     return new Response(
       JSON.stringify(

integration/templates/astro-node/src/pages/discover.astro

@@ -1,6 +1,12 @@
 ---
 import { OrganizationList } from '@clerk/astro/components';
 import Layout from '../layouts/Layout.astro';
+
+const { userId, redirectToSignIn } = Astro.locals.auth();
+
+if (!userId) {
+  return redirectToSignIn();
+}
 ---
 
 <Layout title='Welcome to Astro.'>

integration/templates/astro-node/src/pages/user.astro

@@ -2,6 +2,12 @@
 import { UserProfile } from '@clerk/astro/components';
 import Layout from '../layouts/Layout.astro';
 import StreamUser from '../components/StreamUser.astro';
+
+const { userId, redirectToSignIn } = Astro.locals.auth();
+
+if (!userId) {
+  return redirectToSignIn();
+}
 ---
 
 <Layout title='Welcome to Astro.'>

integration/testUtils/machineAuthHelpers.ts

@@ -262,6 +262,7 @@ export const registerApiKeyAuthTests = (adapter: MachineAuthTestAdapter): void =
     test('should handle multiple token types', async ({ page, context }) => {
       const u = createTestUtils({ app, page, context });
       const url = new URL(adapter.apiKey.path, app.serverUrl).toString();
+      const origin = new URL(app.serverUrl).origin;
 
       await u.po.signIn.goTo();
       await u.po.signIn.waitForMounted();
@@ -271,14 +272,16 @@ export const registerApiKeyAuthTests = (adapter: MachineAuthTestAdapter): void =
       const getRes = await u.page.request.get(url);
       expect(getRes.status()).toBe(401);
 
-      const postWithSessionRes = await u.page.request.post(url);
+      const postWithSessionRes = await u.page.request.post(url, {
+        headers: { Origin: origin },
+      });
       const sessionData = await postWithSessionRes.json();
       expect(postWithSessionRes.status()).toBe(200);
       expect(sessionData.userId).toBe(fakeBapiUser.id);
       expect(sessionData.tokenType).toBe(TokenType.SessionToken);
 
       const postWithApiKeyRes = await u.page.request.post(url, {
-        headers: { Authorization: `Bearer ${fakeAPIKey.secret}` },
+        headers: { Authorization: `Bearer ${fakeAPIKey.secret}`, Origin: origin },
       });
       const apiKeyData = await postWithApiKeyRes.json();
       expect(postWithApiKeyRes.status()).toBe(200);

integration/tests/astro/compatibility.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+
+test.describe('Astro version compatibility @astro', () => {
+  test.describe.configure({ mode: 'serial' });
+
+  let app: Application;
+
+  test.beforeAll(async () => {
+    test.setTimeout(120_000);
+
+    app = await appConfigs.astro.node
+      .clone()
+      .setName('astro-node-v6-smoke')
+      .addDependency('astro', '^6.4.8')
+      .addDependency('@astrojs/node', '^10.1.4')
+      .addDependency('@astrojs/react', '^5.0.7')
+      .commit();
+
+    await app.setup();
+    await app.withEnv(appConfigs.envs.withCustomRoles);
+  });
+
+  test.afterAll(async () => {
+    await app.teardown();
+  });
+
+  test('builds with Astro 6 and custom UserButton menu items', async () => {
+    await app.build();
+
+    expect(app.buildOutput).not.toHaveLength(0);
+    expect(app.buildOutput).not.toContain('Illegal return statement');
+  });
+});

integration/tests/astro/components.test.ts

@@ -416,7 +416,7 @@ testAgainstRunningApps({ withPattern: ['astro.node.withCustomRoles'] })('basic f
   });
 
   // ----- redirect
-  test('redirects to sign-in when unauthenticated (middleware)', async ({ page, context }) => {
+  test('redirects to sign-in when unauthenticated (user page)', async ({ page, context }) => {
     const u = createTestUtils({ app, page, context });
     await u.page.goToAppHome();
     await u.page.getByRole('link', { name: 'User', exact: true }).click();
@@ -432,6 +432,13 @@ testAgainstRunningApps({ withPattern: ['astro.node.withCustomRoles'] })('basic f
     );
   });
 
+  test('redirects to sign-in when unauthenticated (discover page)', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToRelative('/discover');
+    await u.page.waitForURL(`${app.serverUrl}/sign-in?redirect_url=${encodeURIComponent(`${app.serverUrl}/discover`)}`);
+    await u.po.signIn.waitForMounted();
+  });
+
   // ---- protect
   test('only admin', async ({ page, context }) => {
     const u = createTestUtils({ app, page, context });