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 });

.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 });

.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 });

.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 });

.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 });

.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 });

.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 });

.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 });