Communitygithub.com

deangilmoreremix/videoremix.vip2

Clerk을 사용한 Astro 패턴 — 미들웨어, SSR 페이지, 아일랜드 컴포넌트, API 라우트, 정적 렌더링 vs SSR 렌더링. 다음 항목에서 트리거됨: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

videoremix.vip2란 무엇인가요?

이 스킬은 Astro 프레임워크에서 Clerk 인증을 통합하는 방법을 안내합니다. Astro의 SSR(서버 사이드 렌더링)과 정적 사전 렌더링(static prerender) 두 가지 렌더링 모드에서 Clerk이 어떻게 작동하는지 설명하며, 미들웨어 설정, SSR 페이지 보호, 아일랜드 컴포넌트에서의 인증, API 라우트 보호 등 실제 개발에 필요한 핵심 패턴을 다룹니다. 이 스킬은 `@clerk/astro` SDK v3+와 Astro 4.15+를 지원하며, `clerkMiddleware`, `Astro.locals.auth()`, `useAuth()`, `UserButton` 등 주요 API의 사용법을 코드 예제와 함께 제공합니다. 또한 환경 변수 설정, 정적 페이지와 SSR 페이지의 차이, 일반적인 문제와 해결 방법을 표로 정리하여 실무에서 빠르게 참고할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-astro-patterns

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Astro 패턴

SDK: @clerk/astro v3+. Astro 4.15+ 필요.

필요한 사항

작업참고 문서
미들웨어 구성references/middleware.md
SSR 페이지 보호references/ssr-pages.md
아일랜드 컴포넌트에서 Clerk 사용references/island-components.md
API 라우트 인증references/api-routes.md
Astro에서 React와 함께 Clerk 사용references/astro-react.md

개념 모델

Astro는 페이지마다 SSR과 정적 사전 렌더링(static prerender) 두 가지 렌더링 모드를 지원합니다. Clerk은 각 모드에서 다르게 작동합니다.

  • SSR 페이지 — 미들웨어가 채워주는 Astro.locals.auth()를 사용합니다.
  • 정적 페이지 (export const prerender = true) — Clerk 미들웨어가 이를 건너뜁니다. 아일랜드에서 클라이언트 측 훅을 사용하세요.
  • 아일랜드 — React/Vue/Svelte 컴포넌트입니다. @clerk/astro/react의 useAuth() 및 다른 훅을 사용합니다.
요청 → clerkMiddleware() → SSR 페이지 → Astro.locals.auth()
                                ↓
                         아일랜드 (.client) → useAuth() 훅

설정

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

관련 스킬