Communitygithub.com

deangilmoreremix/videoremix.vip2

Astro 模式整合 Clerk — 中介軟體、SSR 頁面、島嶼元件、API 路由、靜態與 SSR 渲染。觸發條件:astro clerk、clerk astro middleware、astro 受保護頁面、clerk 島嶼元件、astro API 路由驗證、clerk astro SSR。

videoremix.vip2 是什麼?

此技能提供了一系列在 Astro 專案中整合 Clerk 身份驗證的完整模式。它涵蓋了 Astro 的兩種渲染模式:SSR(伺服器端渲染)和靜態預渲染,並說明 Clerk 在每種模式下如何運作。主要內容包括設定中介軟體以保護路由、在 SSR 頁面中使用 `Astro.locals.auth()` 進行伺服器端驗證、在 React/Vue/Svelte 等島嶼元件中使用 `useAuth()` 等客戶端鉤子,以及為 API 路由添加驗證。此技能支援 Astro 4.15+ 和 `@clerk/astro` v3+,並提供常見問題的除錯指引(例如 `Astro.locals.auth` 未定義、靜態頁面無驗證等),以及重要的導入映射和環境變數配置說明。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-astro-patterns

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Astro 模式

SDK: @clerk/astro v3+。需要 Astro 4.15+。

你需要什麼?

任務參考文件
配置中介軟體references/middleware.md
保護 SSR 頁面references/ssr-pages.md
在島嶼元件中使用 Clerkreferences/island-components.md
API 路由中的驗證references/api-routes.md
在 Astro 中將 Clerk 與 React 搭配使用references/astro-react.md

心智模型

Astro 的每個頁面有兩種渲染模式:SSR 和靜態預渲染。Clerk 在每種模式下的運作方式不同:

  • SSR 頁面 — 使用由中介軟體填充的 Astro.locals.auth()
  • 靜態頁面 (export const prerender = true) — Clerk 中介軟體會略過此類頁面;請在島嶼中使用客戶端鉤子
  • 島嶼 — React/Vue/Svelte 元件;使用 @clerk/astro/react 提供的 useAuth() 和其他鉤子
Request → clerkMiddleware() → SSR page → Astro.locals.auth()
                                ↓
                         Island (.client) → useAuth() hook

設定

astro.config.mjs

import { defineConfig } from 'astro/config'
import clerk from '@clerk/astro'

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

src/middleware.ts

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

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

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

SSR 頁面驗證

---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---

<h1>儀表板</h1>

常見問題

症狀原因修正方式
Astro.locals.auth 未定義缺少中介軟體在 src/middleware.ts 中加入 clerkMiddleware
驗證在開發環境運作,但正式環境失敗全域設定 output: 'static'對受保護頁面設定 output: 'server' 或 hybrid
靜態頁面沒有驗證預渲染頁面會略過中介軟體使用 export const prerender = false 或移至島嶼元件
島嶼元件對登入無反應缺少 client:load 指令在島嶼元件上加入 client:load 指令

導入映射

項目導入來源
clerkMiddleware、createRouteMatcher@clerk/astro/server
useAuth、useUser、UserButton@clerk/astro/react
Astro 元件(<SignIn> 等)@clerk/astro/components

環境變數

# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

Astro 使用 PUBLIC_ 前綴作為客戶端可存取的變數(非 NEXT_PUBLIC_)。

另請參閱

  • clerk-setup - 初始 Clerk 安裝
  • clerk-custom-ui - 自訂流程與外觀
  • clerk-orgs - B2B 組織

文件

Astro SDK

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

相關技能