Add clerk-setup skill (source: clerk/skills)
This commit is contained in:
@@ -0,0 +1,333 @@
|
||||
---
|
||||
name: clerk-setup
|
||||
description: Add Clerk authentication to any project by following the official quickstart
|
||||
guides.
|
||||
license: MIT
|
||||
allowed-tools: WebFetch
|
||||
compatibility: Requires NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY (or framework-specific equivalents like VITE_CLERK_PUBLISHABLE_KEY for Vite-based apps). Keys can be auto-generated by `clerk init` (temporary development keys, no Clerk account required), or pulled from the Clerk Dashboard. Requires Node.js 20.9.0 or higher.
|
||||
metadata:
|
||||
author: clerk
|
||||
version: 2.5.1
|
||||
---
|
||||
|
||||
# Adding Clerk
|
||||
|
||||
> **Version**: Check `package.json` for the SDK version — see `clerk` skill 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. For agents, the `clerk` CLI handles most of this end to end — see the next section.
|
||||
|
||||
## Agent-first: Provision via CLI
|
||||
|
||||
The `clerk` CLI replaces most Dashboard clicks. Three scenarios cover almost everything:
|
||||
|
||||
### Scenario A — New project, new Clerk app
|
||||
|
||||
```bash
|
||||
clerk init --framework <next|react|vue|nuxt|astro|react-router|tanstack-react-start|expressjs|fastify|expo> -y
|
||||
```
|
||||
|
||||
`clerk init` installs the SDK, wires the project up, and writes the framework-specific publishable + secret keys to the right env file (e.g. `.env.local` for Next.js, `.env` for Vite-based projects).
|
||||
|
||||
#### Getting started without an account
|
||||
|
||||
**No login required.** On a supported framework, unauthenticated `clerk init` provisions a claimable accountless app and writes temporary development keys to the project's env file — no account, no browser, no flag. Don't run `clerk auth login` first. Authenticated (or with `--app` / `--login`) it creates and links a real app via PLAPI instead.
|
||||
|
||||
`--template <b2b-saas|b2c-saas|native|waitlist>` pre-configures the temporary app. Caveats — a signed-out human in an *existing* project still gets the login flow unless they pass `--accountless`; `--keyless` remains a deprecated compatibility alias. `--template`/`--fresh` error on any run that targets a real app; login only auto-claims what `clerk init` created. See [clerk-cli](../clerk-cli/references/auth.md#accountless-operating-without-an-account).
|
||||
|
||||
### Scenario B — Existing project, existing Clerk app
|
||||
|
||||
```bash
|
||||
clerk auth login # one-time OAuth (skip if already logged in)
|
||||
clerk link # autolinks if a CLERK_PUBLISHABLE_KEY is in your .env
|
||||
clerk link --app app_xxx # explicit form, required in agent mode
|
||||
clerk env pull # writes the framework-detected env vars
|
||||
```
|
||||
|
||||
### Scenario C — Existing project, new Clerk app
|
||||
|
||||
```bash
|
||||
clerk auth login
|
||||
clerk apps create "My App" --json # returns the new app_id
|
||||
clerk link --app app_xxx
|
||||
clerk env pull
|
||||
```
|
||||
|
||||
### Daily ops
|
||||
|
||||
```bash
|
||||
clerk env pull # refresh keys (uses linked profile)
|
||||
clerk env pull --instance prod # production keys
|
||||
clerk doctor --json # framework integration health check
|
||||
```
|
||||
|
||||
### Rotate the secret key (replaces Dashboard rotation)
|
||||
|
||||
PLAPI exposes secret-key rotation directly. Use raw `clerk api` until the friendly wrapper ships:
|
||||
|
||||
```bash
|
||||
clerk api --platform POST /v1/platform/applications/<app_id>/rotate_secret_keys \
|
||||
-d '{"delay_old_secrets_expiration_hours": 24, "reason": "scheduled rotation"}'
|
||||
```
|
||||
|
||||
`delay_old_secrets_expiration_hours` keeps the old key valid for the grace period so deploys can roll forward without downtime.
|
||||
|
||||
### Notes for agents
|
||||
|
||||
- Unclaimed accountless apps created by `clerk init` are configurable without an account — see the [accountless command table](../clerk-cli/references/auth.md#accountless-operating-without-an-account) for which commands work and which need a claimed app.
|
||||
- `clerk link` (no flags) only autolinks when a `CLERK_PUBLISHABLE_KEY` is already in `.env` / `.env.local`. Without it, agent mode errors out: "Cannot select an application in agent mode." When that happens, run `clerk apps list --json`, and ask the user which `app_id` to link rather than guessing.
|
||||
- Pass `--json` on `apps list/create`, `users create`, and `doctor` for parseable output.
|
||||
- The CLI auto-detects framework env var names (`VITE_CLERK_PUBLISHABLE_KEY` for Vite, `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` for Next.js, etc.) and target file (`.env.development.local` > `.env.local` > `.env`).
|
||||
|
||||
## Quick Reference (Dashboard fallback)
|
||||
|
||||
If the CLI isn't an option (sandboxed environments, docs walkthroughs), here's the manual Dashboard path:
|
||||
|
||||
| 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](https://dashboard.clerk.com/~/api-keys) |
|
||||
|
||||
> If the project has `components.json` (shadcn/ui), apply the shadcn theme after setup. See `clerk-custom-ui` skill → shadcn Theme.
|
||||
|
||||
## Framework Detection
|
||||
|
||||
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 (deprecated) | Migrate to React Router v7 — use the React Router quickstart below |
|
||||
| `react-router` | React Router (v7+) | `https://clerk.com/docs/react-router/getting-started/quickstart` |
|
||||
| `astro` | Astro | `https://clerk.com/docs/astro/getting-started/quickstart` |
|
||||
| `nuxt` | Nuxt | `https://clerk.com/docs/nuxt/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` |
|
||||
|
||||
For other platforms:
|
||||
- **Chrome Extension**: `https://clerk.com/docs/chrome-extension/getting-started/quickstart`
|
||||
- **Android**: `https://clerk.com/docs/android/getting-started/quickstart`
|
||||
- **iOS**: `https://clerk.com/docs/ios/getting-started/quickstart`
|
||||
- **Vanilla JavaScript**: `https://clerk.com/docs/js-frontend/getting-started/quickstart`
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
User 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 clerk-custom-ui)
|
||||
```
|
||||
|
||||
## Setup Process
|
||||
|
||||
### 1. Detect the Framework
|
||||
|
||||
Read the project's `package.json` and match dependencies to the table above.
|
||||
|
||||
### 2. Fetch the Quickstart Guide
|
||||
|
||||
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."
|
||||
```
|
||||
|
||||
### 3. Follow the Instructions
|
||||
|
||||
Execute each step from the quickstart guide:
|
||||
- Install the required packages
|
||||
- Set up environment variables
|
||||
- Add the provider and proxy/middleware
|
||||
- Create sign-in/sign-up routes if needed
|
||||
- Test the integration
|
||||
|
||||
> **Next.js:** Create `proxy.ts` (Next.js <=15: `middleware.ts`). See the `clerk-nextjs-patterns` skill for middleware strategies.
|
||||
|
||||
> **shadcn/ui detected** (`components.json` exists): ALWAYS apply the shadcn theme. See `clerk-custom-ui` skill → shadcn Theme section.
|
||||
|
||||
### 4. Get API Keys
|
||||
|
||||
Two paths for development API keys:
|
||||
|
||||
**CLI (Automatic)**
|
||||
- `clerk init` writes temporary development keys to the project's env file — no Clerk account required
|
||||
- When you're ready, run `clerk auth login` and the app is claimed into your Clerk account automatically so you can edit it from the Dashboard
|
||||
- Simplest path for new projects
|
||||
|
||||
**Manual (Dashboard)**
|
||||
- Get keys from [dashboard.clerk.com](https://dashboard.clerk.com/~/api-keys)
|
||||
- **Publishable Key**: Starts with `pk_test_` or `pk_live_`
|
||||
- **Secret Key**: Starts with `sk_test_` or `sk_live_`
|
||||
- Set as environment variables: `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`
|
||||
|
||||
## Migrating from Another Auth Provider
|
||||
|
||||
If the project already has authentication, create a migration plan before replacing it.
|
||||
|
||||
### Detect Existing Auth
|
||||
|
||||
Check `package.json` for existing auth libraries:
|
||||
- `next-auth` / `@auth/core` → NextAuth/Auth.js
|
||||
- `@supabase/supabase-js` → Supabase Auth
|
||||
- `firebase` / `firebase-admin` → Firebase Auth
|
||||
- `@aws-amplify/auth` → AWS Cognito
|
||||
- `auth0` / `@auth0/nextjs-auth0` → Auth0
|
||||
- `passport` → Passport.js
|
||||
- Custom JWT/session implementation
|
||||
|
||||
### Migration Process
|
||||
|
||||
1. **Audit current auth** - Identify all auth touchpoints:
|
||||
- Sign-in/sign-up pages
|
||||
- Session/token handling
|
||||
- Protected routes and middleware
|
||||
- User data storage (database tables, external IDs)
|
||||
- OAuth providers configured
|
||||
|
||||
2. **Create migration plan** - Consider:
|
||||
- **User data export** - Export users and import via Clerk's Backend API
|
||||
- **Password hashes** - Clerk can upgrade hashes to Bcrypt transparently
|
||||
- **External IDs** - Store legacy user IDs as `external_id` in Clerk
|
||||
- **Session handling** - Existing sessions will terminate on switch
|
||||
|
||||
3. **Choose migration strategy**:
|
||||
- **Big bang** - Switch all users at once (simpler, requires maintenance window)
|
||||
- **Trickle migration** - Run both systems temporarily (lower risk, higher complexity)
|
||||
|
||||
### Migration Reference
|
||||
|
||||
- **Migration Overview**: https://clerk.com/docs/guides/development/migrating/overview
|
||||
|
||||
## SDK Notes
|
||||
|
||||
### Package Names
|
||||
|
||||
| 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-react` and `@clerk/clerk-expo` (with `clerk-` prefix).
|
||||
|
||||
### ClerkProvider Placement (Next.js)
|
||||
|
||||
`ClerkProvider` must be placed **inside `<body>`**, not wrapping `<html>`:
|
||||
|
||||
```tsx
|
||||
// root layout.tsx
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html>
|
||||
<body>
|
||||
<ClerkProvider>{children}</ClerkProvider>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
> **Core 2 ONLY (skip if current SDK):** `ClerkProvider` can wrap `<html>` directly.
|
||||
|
||||
### Dynamic Rendering (Next.js)
|
||||
|
||||
For dynamic rendering with auth data, use the `dynamic` prop:
|
||||
|
||||
```tsx
|
||||
<ClerkProvider dynamic>{children}</ClerkProvider>
|
||||
```
|
||||
|
||||
### Node.js Requirement
|
||||
|
||||
Requires **Node.js 20.9.0** or higher.
|
||||
|
||||
> **Core 2 ONLY (skip if current SDK):** Minimum Node.js 18.17.0.
|
||||
|
||||
### Themes Package
|
||||
|
||||
Themes are installed from `@clerk/ui`:
|
||||
|
||||
```bash
|
||||
npm install @clerk/ui
|
||||
```
|
||||
|
||||
> **Core 2 ONLY (skip if current SDK):** Themes are from `@clerk/themes` instead of `@clerk/ui`.
|
||||
|
||||
### shadcn Theme
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
npm install @clerk/ui
|
||||
```
|
||||
|
||||
```tsx
|
||||
import { shadcn } from '@clerk/ui/themes'
|
||||
|
||||
<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>
|
||||
```
|
||||
|
||||
Also import the shadcn CSS in your global styles:
|
||||
```css
|
||||
@import 'tailwindcss';
|
||||
@import '@clerk/ui/themes/shadcn.css';
|
||||
```
|
||||
|
||||
> **Core 2 ONLY (skip if current SDK):** Import from `@clerk/themes` and `@clerk/themes/shadcn.css` instead.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
> **Run `clerk doctor` first.** It checks framework integration, env vars, middleware presence, and SDK install status. Fixes a lot of these in one shot.
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Missing `await` on `auth()` | In Next.js 15+, `auth()` is async: `const { userId } = await auth()` |
|
||||
| Exposing `CLERK_SECRET_KEY` | Never use the secret key in client code; only `NEXT_PUBLIC_*` keys are safe |
|
||||
| Missing middleware matcher | Include API routes: `matcher: ['/((?!.*\\..*|_next).*)', '/']` |
|
||||
| ClerkProvider placement | Must be inside `<body>` in root layout (Core 2: could wrap `<html>`) |
|
||||
| Auth routes not public | Allow `/sign-in`, `/sign-up` in middleware config |
|
||||
| Landing page requires auth | To keep "/" public, exclude it: `matcher: ['/((?!.*\\..*|_next|^/$).*)', '/api/(.*)']` |
|
||||
| Wrong import path | Server code uses `@clerk/nextjs/server`, client uses `@clerk/nextjs` |
|
||||
| Wrong package name | Use `@clerk/react` not `@clerk/clerk-react` (Core 2 naming) |
|
||||
|
||||
## See Also
|
||||
|
||||
- `clerk-custom-ui` - Custom sign-in/up components
|
||||
- `clerk-nextjs-patterns` - Advanced Next.js patterns
|
||||
- `clerk-react-patterns` - React SPA patterns
|
||||
- `clerk-react-router-patterns` - React Router patterns
|
||||
- `clerk-vue-patterns` - Vue patterns
|
||||
- `clerk-nuxt-patterns` - Nuxt patterns
|
||||
- `clerk-astro-patterns` - Astro patterns
|
||||
- `clerk-tanstack-patterns` - TanStack Start patterns
|
||||
- `clerk-chrome-extension-patterns` - Chrome Extension patterns
|
||||
- `clerk-orgs` - B2B multi-tenant organizations
|
||||
- `clerk-webhooks` - Webhook → database sync
|
||||
- `clerk-testing` - E2E testing setup
|
||||
- `clerk-swift` - Native iOS auth
|
||||
- `clerk-android` - Native Android auth
|
||||
- `clerk-expo` - Expo / React Native auth
|
||||
- `clerk-backend-api` - Backend REST API explorer
|
||||
|
||||
## Documentation
|
||||
|
||||
- **Quickstart Overview**: https://clerk.com/docs/getting-started/quickstart/overview
|
||||
- **Migration Guide**: https://clerk.com/docs/guides/development/migrating/overview
|
||||
- **Full Documentation**: https://clerk.com/docs
|
||||
@@ -0,0 +1,74 @@
|
||||
{
|
||||
"skill_name": "clerk-setup",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "hey i just created a new next.js app with create-next-app and i want to add auth. i heard clerk is good, can you set it up? im using the app router btw and tailwind. project is at ./my-saas-app",
|
||||
"expected_output": "Installs @clerk/nextjs, wraps layout with ClerkProvider inside <body>, creates middleware.ts with clerkMiddleware, sets up .env.local with publishable and secret keys, detects shadcn if present",
|
||||
"files": [],
|
||||
"expectations": [
|
||||
"Installs @clerk/nextjs via npm/pnpm/bun",
|
||||
"Adds ClerkProvider to root layout.tsx inside <body> tag, not wrapping <html>",
|
||||
"Creates middleware.ts (or proxy.ts for Next.js 16+) with clerkMiddleware export",
|
||||
"Creates or updates .env.local with NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY",
|
||||
"Does NOT install @clerk/clerk-react or any non-Next.js Clerk package",
|
||||
"Mentions getting API keys from dashboard.clerk.com or via `clerk init` temporary development keys"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "im building a rest api with express and typescript, no frontend. i need to protect some routes with authentication. can you add clerk? i want /api/public to be open and everything under /api/private/* to require auth",
|
||||
"expected_output": "Installs @clerk/express, adds clerkMiddleware globally, uses requireAuth for protected routes, keeps public routes open",
|
||||
"files": [],
|
||||
"expectations": [
|
||||
"Installs @clerk/express (not @clerk/nextjs)",
|
||||
"Adds clerkMiddleware() to the Express app",
|
||||
"Shows how to protect /api/private/* routes with requireAuth or getAuth check",
|
||||
"Leaves /api/public accessible without auth",
|
||||
"Does NOT create React components, ClerkProvider, or any frontend code",
|
||||
"Sets up CLERK_SECRET_KEY (and optionally CLERK_PUBLISHABLE_KEY) env vars"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "we have a next.js app thats been using next-auth with google and github oauth for about a year. we want to switch to clerk because next-auth sessions keep expiring randomly. theres about 2000 users in our postgres db. how do we migrate without losing everyone?",
|
||||
"expected_output": "Migration plan: audit current NextAuth setup, export users via Clerk Backend API, handle OAuth provider mapping, plan session transition",
|
||||
"files": [],
|
||||
"expectations": [
|
||||
"Detects or acknowledges existing NextAuth/next-auth setup",
|
||||
"Addresses user data migration (2000 users) - mentions Clerk Backend API import or trickle migration",
|
||||
"Addresses OAuth provider continuity (Google and GitHub)",
|
||||
"Mentions that existing sessions will terminate during switch",
|
||||
"Suggests either big-bang or gradual migration strategy",
|
||||
"Does NOT just install Clerk and ignore the existing auth system"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "setting up a react spa with vite for an internal tool at work. no ssr, no next.js. just plain react 19 + react-router. need login/logout. whats the quickest way to get clerk working?",
|
||||
"expected_output": "Installs @clerk/react, wraps app with ClerkProvider, no middleware needed for SPA",
|
||||
"files": [],
|
||||
"expectations": [
|
||||
"Installs @clerk/react (not @clerk/nextjs or @clerk/clerk-react)",
|
||||
"Wraps app root with ClerkProvider and passes publishableKey",
|
||||
"Does NOT create middleware.ts or proxy.ts (not applicable to SPAs)",
|
||||
"Does NOT reference Next.js-specific patterns like server components or auth()",
|
||||
"Shows SignIn/SignUp components or redirect-based auth flow",
|
||||
"Sets up NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY or VITE_CLERK_PUBLISHABLE_KEY env var"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "i have an astro site with some react islands, its mostly static but i want to add a members-only section. never used clerk before. using bun as my package manager",
|
||||
"expected_output": "Installs @clerk/astro via bun, configures Astro integration, sets up protected routes for members-only section",
|
||||
"files": [],
|
||||
"expectations": [
|
||||
"Installs @clerk/astro using bun (not npm or pnpm)",
|
||||
"Configures Clerk as an Astro integration in astro.config",
|
||||
"Shows how to protect specific routes for the members-only section",
|
||||
"Sets up environment variables for Clerk keys",
|
||||
"Does NOT install @clerk/nextjs or create Next.js-specific files"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user