clerk-setup by clerk/skills
npx skills add https://github.com/clerk/skills --skill clerk-setup版本:查看
package.json中的 SDK 版本——版本表请参考clerkskill。Core 2 的差异已在行内用> **仅限 Core 2(如果当前是 SDK 则跳过):**标注说明。
此 skill 通过遵循官方快速入门文档来设置 Clerk 以进行身份验证。
| 步骤 | 操作 |
|---|---|
| 1. 检测框架 | 检查 package.json 依赖项 |
| 2. 获取快速入门指南 | 在相应的文档 URL 上使用 WebFetch |
| 3. 遵循说明 | 执行步骤;创建 proxy.ts(Next.js <=15:middleware.ts) |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 4. 获取 API 密钥 | 从 dashboard.clerk.com 获取 |
如果项目有
components.json(shadcn/ui),则在设置后应用 shadcn 主题。参见custom-ui/→ shadcn 主题。
检查 package.json 以识别框架:
| 依赖项 | 框架 | 快速入门 URL |
|---|---|---|
next | Next.js | https://clerk.com/docs/nextjs/getting-started/quickstart |
@remix-run/react | Remix | https://clerk.com/docs/remix/getting-started/quickstart |
astro | Astro | https://clerk.com/docs/astro/getting-started/quickstart |
nuxt | Nuxt | https://clerk.com/docs/nuxt/getting-started/quickstart |
react-router | React Router | https://clerk.com/docs/react-router/getting-started/quickstart |
@tanstack/react-start | TanStack Start | https://clerk.com/docs/tanstack-react-start/getting-started/quickstart |
react(无框架) | React SPA | https://clerk.com/docs/react/getting-started/quickstart |
vue | Vue | https://clerk.com/docs/vue/getting-started/quickstart |
express | Express | https://clerk.com/docs/expressjs/getting-started/quickstart |
fastify | Fastify | https://clerk.com/docs/fastify/getting-started/quickstart |
expo | Expo | https://clerk.com/docs/expo/getting-started/quickstart |
对于其他平台:
https://clerk.com/docs/chrome-extension/getting-started/quickstarthttps://clerk.com/docs/android/getting-started/quickstarthttps://clerk.com/docs/ios/getting-started/quickstarthttps://clerk.com/docs/js-frontend/getting-started/quickstartUser Request: "Add Clerk" / "Add authentication"
│
├─ Read package.json
│
├─ Existing auth detected?
│ ├─ YES → Audit → Migration plan
│ └─ NO → Fresh install
│
├─ Identify framework → WebFetch quickstart → Follow instructions
│ └─ Next.js? → Create proxy.ts (Next.js <=15: middleware.ts)
│
└─ components.json exists? → YES → Apply shadcn theme (see custom-ui/)
读取项目的 package.json 并根据上表匹配依赖项。
使用 WebFetch 获取检测到的框架的官方快速入门指南:
WebFetch: https://clerk.com/docs/{framework}/getting-started/quickstart
Prompt: "Extract the complete setup instructions including all code snippets, file paths, and configuration steps."
执行快速入门指南中的每一步:
Next.js: 创建
proxy.ts(Next.js <=15:middleware.ts)。参见nextjs-patterns/references/middleware-strategies.md。
检测到 shadcn/ui(存在
components.json):始终应用 shadcn 主题。参见custom-ui/→ shadcn 主题部分。
获取开发 API 密钥的两种途径:
无密钥(自动)
手动(仪表板)
pk_test_ 或 pk_live_ 开头sk_test_ 或 sk_live_ 开头NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY如果项目已有身份验证,请在替换之前创建迁移计划。
检查 package.json 中现有的身份验证库:
next-auth / @auth/core → NextAuth/Auth.js@supabase/supabase-js → Supabase Authfirebase / firebase-admin → Firebase Auth@aws-amplify/auth → AWS Cognitoauth0 / @auth0/nextjs-auth0 → Auth0passport → Passport.js审核当前身份验证 - 识别所有身份验证接触点:
创建迁移计划 - 考虑:
external_id 存储在 Clerk 中选择迁移策略:
| 包 | 安装 |
|---|---|
| Next.js | @clerk/nextjs |
| React | @clerk/react |
| Expo | @clerk/expo |
| React Router | @clerk/react-router |
| TanStack Start | @clerk/tanstack-react-start |
仅限 Core 2(如果当前是 SDK 则跳过): React 和 Expo 包的名称不同:
@clerk/clerk-react和@clerk/clerk-expo(带有clerk-前缀)。
ClerkProvider 必须放置在 <body> 内部,而不是包裹 <html>:
// root layout.tsx
export default function RootLayout({ children }) {
return (
<html>
<body>
<ClerkProvider>{children}</ClerkProvider>
</body>
</html>
)
}
仅限 Core 2(如果当前是 SDK 则跳过):
ClerkProvider可以直接包裹<html>。
对于包含身份验证数据的动态渲染,使用 dynamic 属性:
<ClerkProvider dynamic>{children}</ClerkProvider>
需要 Node.js 20.9.0 或更高版本。
仅限 Core 2(如果当前是 SDK 则跳过): 最低 Node.js 18.17.0。
主题从 @clerk/ui 安装:
npm install @clerk/ui
仅限 Core 2(如果当前是 SDK 则跳过): 主题来自
@clerk/themes而不是@clerk/ui。
如果项目使用 shadcn/ui(检查项目根目录中是否存在 components.json),请应用 shadcn 主题,以便 Clerk 组件与应用程序的设计系统匹配:
npm install @clerk/ui
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>
同时,在全局样式中导入 shadcn CSS:
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
仅限 Core 2(如果当前是 SDK 则跳过): 从
@clerk/themes和@clerk/themes/shadcn.css导入。
| 级别 | 问题 | 解决方案 |
|---|---|---|
| 严重 | 在 auth() 上缺少 await | 在 Next.js 15+ 中,auth() 是异步的:const { userId } = await auth() |
| 严重 | 暴露 CLERK_SECRET_KEY | 切勿在客户端代码中使用密钥;只有 NEXT_PUBLIC_* 密钥是安全的 |
| 高 | 缺少中间件匹配器 | 包含 API 路由:`matcher: ['/((?!.\.. |
| 高 | ClerkProvider 放置位置 | 必须在根布局的 <body> 内部(Core 2:可以包裹 <html>) |
| 高 | 身份验证路由未公开 | 在中间件配置中允许 /sign-in、/sign-up |
| 高 | 着陆页需要身份验证 | 要保持 "/" 公开,请排除它:`matcher: ['/((?!.\.. |
| 中 | 错误的导入路径 | 服务器代码使用 @clerk/nextjs/server,客户端使用 @clerk/nextjs |
| 中 | 错误的包名称 | 使用 @clerk/react 而不是 @clerk/clerk-react(Core 2 命名) |
custom-ui/ - 自定义登录/注册组件webhooks/ - Webhook → 数据库同步orgs/ - B2B 多租户组织testing/ - E2E 测试设置nextjs-patterns/ - 高级 Next.js 模式每周安装量
1.9K
仓库
GitHub 星标数
22
首次出现
2026年1月30日
安全审计
安装于
codex1.6K
opencode1.6K
gemini-cli1.6K
github-copilot1.6K
amp1.5K
kimi-cli1.5K
Version : Check
package.jsonfor the SDK version — seeclerkskill for the version table. Core 2 differences are noted inline with> **Core 2 ONLY (skip if current SDK):**callouts.
This skill sets up Clerk for authentication by following the official quickstart documentation.
| Step | Action |
|---|---|
| 1. Detect framework | Check package.json dependencies |
| 2. Fetch quickstart | Use WebFetch on the appropriate docs URL |
| 3. Follow instructions | Execute steps; create proxy.ts (Next.js <=15: middleware.ts) |
| 4. Get API keys | From dashboard.clerk.com |
If the project has
components.json(shadcn/ui), apply the shadcn theme after setup. Seecustom-ui/→ shadcn Theme.
Check package.json to identify the framework:
| Dependency | Framework | Quickstart URL |
|---|---|---|
next | Next.js | https://clerk.com/docs/nextjs/getting-started/quickstart |
@remix-run/react | Remix | https://clerk.com/docs/remix/getting-started/quickstart |
astro | Astro | https://clerk.com/docs/astro/getting-started/quickstart |
For other platforms:
https://clerk.com/docs/chrome-extension/getting-started/quickstarthttps://clerk.com/docs/android/getting-started/quickstarthttps://clerk.com/docs/ios/getting-started/quickstarthttps://clerk.com/docs/js-frontend/getting-started/quickstartUser Request: "Add Clerk" / "Add authentication"
│
├─ Read package.json
│
├─ Existing auth detected?
│ ├─ YES → Audit → Migration plan
│ └─ NO → Fresh install
│
├─ Identify framework → WebFetch quickstart → Follow instructions
│ └─ Next.js? → Create proxy.ts (Next.js <=15: middleware.ts)
│
└─ components.json exists? → YES → Apply shadcn theme (see custom-ui/)
Read the project's package.json and match dependencies to the table above.
Use WebFetch to retrieve the official quickstart for the detected framework:
WebFetch: https://clerk.com/docs/{framework}/getting-started/quickstart
Prompt: "Extract the complete setup instructions including all code snippets, file paths, and configuration steps."
Execute each step from the quickstart guide:
Next.js: Create
proxy.ts(Next.js <=15:middleware.ts). Seenextjs-patterns/references/middleware-strategies.md.
shadcn/ui detected (
components.jsonexists): ALWAYS apply the shadcn theme. Seecustom-ui/→ shadcn Theme section.
Two paths for development API keys:
Keyless (Automatic)
Manual (Dashboard)
pk_test_ or pk_live_sk_test_ or sk_live_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEYIf the project already has authentication, create a migration plan before replacing it.
Check package.json for existing auth libraries:
next-auth / @auth/core → NextAuth/Auth.js@supabase/supabase-js → Supabase Authfirebase / firebase-admin → Firebase Auth@aws-amplify/auth → AWS Cognitoauth0 / @auth0/nextjs-auth0 → Auth0passport → Passport.jsAudit current auth - Identify all auth touchpoints:
Create migration plan - Consider:
external_id in ClerkChoose migration strategy :
| Package | Install |
|---|---|
| Next.js | @clerk/nextjs |
| React | @clerk/react |
| Expo | @clerk/expo |
| React Router | @clerk/react-router |
| TanStack Start | @clerk/tanstack-react-start |
Core 2 ONLY (skip if current SDK): React and Expo packages have different names:
@clerk/clerk-reactand@clerk/clerk-expo(withclerk-prefix).
ClerkProvider must be placed inside<body>, not wrapping <html>:
// root layout.tsx
export default function RootLayout({ children }) {
return (
<html>
<body>
<ClerkProvider>{children}</ClerkProvider>
</body>
</html>
)
}
Core 2 ONLY (skip if current SDK):
ClerkProvidercan wrap<html>directly.
For dynamic rendering with auth data, use the dynamic prop:
<ClerkProvider dynamic>{children}</ClerkProvider>
Requires Node.js 20.9.0 or higher.
Core 2 ONLY (skip if current SDK): Minimum Node.js 18.17.0.
Themes are installed from @clerk/ui:
npm install @clerk/ui
Core 2 ONLY (skip if current SDK): Themes are from
@clerk/themesinstead of@clerk/ui.
If the project uses shadcn/ui (check for components.json in the project root), apply the shadcn theme so Clerk components match the app's design system:
npm install @clerk/ui
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>
Also import the shadcn CSS in your global styles:
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
Core 2 ONLY (skip if current SDK): Import from
@clerk/themesand@clerk/themes/shadcn.cssinstead.
| Level | Issue | Solution |
|---|---|---|
| CRITICAL | Missing await on auth() | In Next.js 15+, auth() is async: const { userId } = await auth() |
| CRITICAL | Exposing CLERK_SECRET_KEY | Never use secret key in client code; only NEXT_PUBLIC_* keys are safe |
| HIGH | Missing middleware matcher | Include API routes: `matcher: ['/((?!.\.. |
| HIGH |
custom-ui/ - Custom sign-in/up componentswebhooks/ - Webhook → database syncorgs/ - B2B multi-tenant organizationstesting/ - E2E testing setupnextjs-patterns/ - Advanced Next.js patternsWeekly Installs
1.9K
Repository
GitHub Stars
22
First Seen
Jan 30, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex1.6K
opencode1.6K
gemini-cli1.6K
github-copilot1.6K
amp1.5K
kimi-cli1.5K
99,500 周安装
nuxt |
| Nuxt |
https://clerk.com/docs/nuxt/getting-started/quickstart |
react-router | React Router | https://clerk.com/docs/react-router/getting-started/quickstart |
@tanstack/react-start | TanStack Start | https://clerk.com/docs/tanstack-react-start/getting-started/quickstart |
react (no framework) | React SPA | https://clerk.com/docs/react/getting-started/quickstart |
vue | Vue | https://clerk.com/docs/vue/getting-started/quickstart |
express | Express | https://clerk.com/docs/expressjs/getting-started/quickstart |
fastify | Fastify | https://clerk.com/docs/fastify/getting-started/quickstart |
expo | Expo | https://clerk.com/docs/expo/getting-started/quickstart |
| ClerkProvider placement |
Must be inside <body> in root layout (Core 2: could wrap <html>) |
| HIGH | Auth routes not public | Allow /sign-in, /sign-up in middleware config |
| HIGH | Landing page requires auth | To keep "/" public, exclude it: `matcher: ['/((?!.\.. |
| MEDIUM | Wrong import path | Server code uses @clerk/nextjs/server, client uses @clerk/nextjs |
| MEDIUM | Wrong package name | Use @clerk/react not @clerk/clerk-react (Core 2 naming) |