{"id":14584,"plugin_id":"plugin_asdk_app_6a9a3c1cd0108191807da33c4cd319ed","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:09:49.473Z","digest":"19825e60d4760c4a2d458f60dabf8f104d6212d468a1c998be1236981244d962","against":null,"payload":{"name":"clerk-setup","description":"Add Clerk authentication to any project by following the official quickstart guides.","included_files":[{"relative_path":"evals/evals.json","size_in_bytes":4544}],"skill_md_contents":"---\nname: clerk-setup\ndescription: Add Clerk authentication to any project by following the official quickstart\n  guides.\nlicense: MIT\nallowed-tools: WebFetch\ncompatibility: 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.\nmetadata:\n  author: clerk\n  version: 2.5.0\n---\n\n# Adding Clerk\n\n> **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.\n\nThis 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.\n\n## Agent-first: Provision via CLI\n\nThe `clerk` CLI replaces most Dashboard clicks. Three scenarios cover almost everything:\n\n### Scenario A — New project, new Clerk app\n\n```bash\nclerk init --framework <next|react|vue|nuxt|astro|react-router|tanstack-react-start|expressjs|fastify|expo> -y\n```\n\n`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).\n\n**No login required.** Unauthenticated, `clerk init` 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.\n\n`--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 `--keyless`; `--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).\n\n### Scenario B — Existing project, existing Clerk app\n\n```bash\nclerk auth login                      # one-time OAuth (skip if already logged in)\nclerk link                            # autolinks if a CLERK_PUBLISHABLE_KEY is in your .env\nclerk link --app app_xxx              # explicit form, required in agent mode\nclerk env pull                        # writes the framework-detected env vars\n```\n\n### Scenario C — Existing project, new Clerk app\n\n```bash\nclerk auth login\nclerk apps create \"My App\" --json     # returns the new app_id\nclerk link --app app_xxx\nclerk env pull\n```\n\n### Daily ops\n\n```bash\nclerk env pull                        # refresh keys (uses linked profile)\nclerk env pull --instance prod        # production keys\nclerk doctor --json                   # framework integration health check\n```\n\n### Rotate the secret key (replaces Dashboard rotation)\n\nPLAPI exposes secret-key rotation directly. Use raw `clerk api` until the friendly wrapper ships:\n\n```bash\nclerk api --platform POST /v1/platform/applications/<app_id>/rotate_secret_keys \\\n  -d '{\"delay_old_secrets_expiration_hours\": 24, \"reason\": \"scheduled rotation\"}'\n```\n\n`delay_old_secrets_expiration_hours` keeps the old key valid for the grace period so deploys can roll forward without downtime.\n\n### Notes for agents\n\n- Unclaimed apps created by `clerk init` are configurable without an account — see the [no-account command table](../clerk-cli/references/auth.md#accountless-operating-without-an-account) for which commands work and which need a claimed app.\n- `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.\n- Pass `--json` on `apps list/create`, `users create`, and `doctor` for parseable output.\n- 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`).\n\n## Quick Reference (Dashboard fallback)\n\nIf the CLI isn't an option (sandboxed environments, docs walkthroughs), here's the manual Dashboard path:\n\n| Step | Action |\n|------|--------|\n| 1. Detect framework | Check `package.json` dependencies |\n| 2. Fetch quickstart | Use WebFetch on the appropriate docs URL |\n| 3. Follow instructions | Execute steps; create `proxy.ts` (Next.js <=15: `middleware.ts`) |\n| 4. Get API keys | From [dashboard.clerk.com](https://dashboard.clerk.com/~/api-keys) |\n\n> If the project has `components.json` (shadcn/ui), apply the shadcn theme after setup. See `clerk-custom-ui` skill → shadcn Theme.\n\n## Framework Detection\n\nCheck `package.json` to identify the framework:\n\n| Dependency | Framework | Quickstart URL |\n|------------|-----------|----------------|\n| `next` | Next.js | `https://clerk.com/docs/nextjs/getting-started/quickstart` |\n| `@remix-run/react` | Remix (deprecated) | Migrate to React Router v7 — use the React Router quickstart below |\n| `react-router` | React Router (v7+) | `https://clerk.com/docs/react-router/getting-started/quickstart` |\n| `astro` | Astro | `https://clerk.com/docs/astro/getting-started/quickstart` |\n| `nuxt` | Nuxt | `https://clerk.com/docs/nuxt/getting-started/quickstart` |\n| `@tanstack/react-start` | TanStack Start | `https://clerk.com/docs/tanstack-react-start/getting-started/quickstart` |\n| `react` (no framework) | React SPA | `https://clerk.com/docs/react/getting-started/quickstart` |\n| `vue` | Vue | `https://clerk.com/docs/vue/getting-started/quickstart` |\n| `express` | Express | `https://clerk.com/docs/expressjs/getting-started/quickstart` |\n| `fastify` | Fastify | `https://clerk.com/docs/fastify/getting-started/quickstart` |\n| `expo` | Expo | `https://clerk.com/docs/expo/getting-started/quickstart` |\n\nFor other platforms:\n- **Chrome Extension**: `https://clerk.com/docs/chrome-extension/getting-started/quickstart`\n- **Android**: `https://clerk.com/docs/android/getting-started/quickstart`\n- **iOS**: `https://clerk.com/docs/ios/getting-started/quickstart`\n- **Vanilla JavaScript**: `https://clerk.com/docs/js-frontend/getting-started/quickstart`\n\n## Decision Tree\n\n```\nUser Request: \"Add Clerk\" / \"Add authentication\"\n    │\n    ├─ Read package.json\n    │\n    ├─ Existing auth detected?\n    │   ├─ YES → Audit → Migration plan\n    │   └─ NO → Fresh install\n    │\n    ├─ Identify framework → WebFetch quickstart → Follow instructions\n    │   └─ Next.js? → Create proxy.ts (Next.js <=15: middleware.ts)\n    │\n    └─ components.json exists? → YES → Apply shadcn theme (see clerk-custom-ui)\n```\n\n## Setup Process\n\n### 1. Detect the Framework\n\nRead the project's `package.json` and match dependencies to the table above.\n\n### 2. Fetch the Quickstart Guide\n\nUse WebFetch to retrieve the official quickstart for the detected framework:\n\n```\nWebFetch: https://clerk.com/docs/{framework}/getting-started/quickstart\nPrompt: \"Extract the complete setup instructions including all code snippets, file paths, and configuration steps.\"\n```\n\n### 3. Follow the Instructions\n\nExecute each step from the quickstart guide:\n- Install the required packages\n- Set up environment variables\n- Add the provider and proxy/middleware\n- Create sign-in/sign-up routes if needed\n- Test the integration\n\n> **Next.js:** Create `proxy.ts` (Next.js <=15: `middleware.ts`). See the `clerk-nextjs-patterns` skill for middleware strategies.\n\n> **shadcn/ui detected** (`components.json` exists): ALWAYS apply the shadcn theme. See `clerk-custom-ui` skill → shadcn Theme section.\n\n### 4. Get API Keys\n\nTwo paths for development API keys:\n\n**CLI (Automatic)**\n- `clerk init` writes temporary development keys to the project's env file — no Clerk account required\n- 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\n- Simplest path for new projects\n\n**Manual (Dashboard)**\n- Get keys from [dashboard.clerk.com](https://dashboard.clerk.com/~/api-keys)\n- **Publishable Key**: Starts with `pk_test_` or `pk_live_`\n- **Secret Key**: Starts with `sk_test_` or `sk_live_`\n- Set as environment variables: `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`\n\n## Migrating from Another Auth Provider\n\nIf the project already has authentication, create a migration plan before replacing it.\n\n### Detect Existing Auth\n\nCheck `package.json` for existing auth libraries:\n- `next-auth` / `@auth/core` → NextAuth/Auth.js\n- `@supabase/supabase-js` → Supabase Auth\n- `firebase` / `firebase-admin` → Firebase Auth\n- `@aws-amplify/auth` → AWS Cognito\n- `auth0` / `@auth0/nextjs-auth0` → Auth0\n- `passport` → Passport.js\n- Custom JWT/session implementation\n\n### Migration Process\n\n1. **Audit current auth** - Identify all auth touchpoints:\n   - Sign-in/sign-up pages\n   - Session/token handling\n   - Protected routes and middleware\n   - User data storage (database tables, external IDs)\n   - OAuth providers configured\n\n2. **Create migration plan** - Consider:\n   - **User data export** - Export users and import via Clerk's Backend API\n   - **Password hashes** - Clerk can upgrade hashes to Bcrypt transparently\n   - **External IDs** - Store legacy user IDs as `external_id` in Clerk\n   - **Session handling** - Existing sessions will terminate on switch\n\n3. **Choose migration strategy**:\n   - **Big bang** - Switch all users at once (simpler, requires maintenance window)\n   - **Trickle migration** - Run both systems temporarily (lower risk, higher complexity)\n\n### Migration Reference\n\n- **Migration Overview**: https://clerk.com/docs/guides/development/migrating/overview\n\n## SDK Notes\n\n### Package Names\n\n| Package | Install |\n|---------|---------|\n| Next.js | `@clerk/nextjs` |\n| React | `@clerk/react` |\n| Expo | `@clerk/expo` |\n| React Router | `@clerk/react-router` |\n| TanStack Start | `@clerk/tanstack-react-start` |\n\n> **Core 2 ONLY (skip if current SDK):** React and Expo packages have different names: `@clerk/clerk-react` and `@clerk/clerk-expo` (with `clerk-` prefix).\n\n### ClerkProvider Placement (Next.js)\n\n`ClerkProvider` must be placed **inside `<body>`**, not wrapping `<html>`:\n\n```tsx\n// root layout.tsx\nexport default function RootLayout({ children }) {\n  return (\n    <html>\n      <body>\n        <ClerkProvider>{children}</ClerkProvider>\n      </body>\n    </html>\n  )\n}\n```\n\n> **Core 2 ONLY (skip if current SDK):** `ClerkProvider` can wrap `<html>` directly.\n\n### Dynamic Rendering (Next.js)\n\nFor dynamic rendering with auth data, use the `dynamic` prop:\n\n```tsx\n<ClerkProvider dynamic>{children}</ClerkProvider>\n```\n\n### Node.js Requirement\n\nRequires **Node.js 20.9.0** or higher.\n\n> **Core 2 ONLY (skip if current SDK):** Minimum Node.js 18.17.0.\n\n### Themes Package\n\nThemes are installed from `@clerk/ui`:\n\n```bash\nnpm install @clerk/ui\n```\n\n> **Core 2 ONLY (skip if current SDK):** Themes are from `@clerk/themes` instead of `@clerk/ui`.\n\n### shadcn Theme\n\nIf 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:\n\n```bash\nnpm install @clerk/ui\n```\n\n```tsx\nimport { shadcn } from '@clerk/ui/themes'\n\n<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>\n```\n\nAlso import the shadcn CSS in your global styles:\n```css\n@import 'tailwindcss';\n@import '@clerk/ui/themes/shadcn.css';\n```\n\n> **Core 2 ONLY (skip if current SDK):** Import from `@clerk/themes` and `@clerk/themes/shadcn.css` instead.\n\n## Common Pitfalls\n\n> **Run `clerk doctor` first.** It checks framework integration, env vars, middleware presence, and SDK install status. Fixes a lot of these in one shot.\n\n| Issue | Solution |\n|-------|----------|\n| Missing `await` on `auth()` | In Next.js 15+, `auth()` is async: `const { userId } = await auth()` |\n| Exposing `CLERK_SECRET_KEY` | Never use the secret key in client code; only `NEXT_PUBLIC_*` keys are safe |\n| Missing middleware matcher | Include API routes: `matcher: ['/((?!.*\\\\..*|_next).*)', '/']` |\n| ClerkProvider placement | Must be inside `<body>` in root layout (Core 2: could wrap `<html>`) |\n| Auth routes not public | Allow `/sign-in`, `/sign-up` in middleware config |\n| Landing page requires auth | To keep \"/\" public, exclude it: `matcher: ['/((?!.*\\\\..*|_next|^/$).*)', '/api/(.*)']` |\n| Wrong import path | Server code uses `@clerk/nextjs/server`, client uses `@clerk/nextjs` |\n| Wrong package name | Use `@clerk/react` not `@clerk/clerk-react` (Core 2 naming) |\n\n## See Also\n\n- `clerk-custom-ui` - Custom sign-in/up components\n- `clerk-nextjs-patterns` - Advanced Next.js patterns\n- `clerk-react-patterns` - React SPA patterns\n- `clerk-react-router-patterns` - React Router patterns\n- `clerk-vue-patterns` - Vue patterns\n- `clerk-nuxt-patterns` - Nuxt patterns\n- `clerk-astro-patterns` - Astro patterns\n- `clerk-tanstack-patterns` - TanStack Start patterns\n- `clerk-chrome-extension-patterns` - Chrome Extension patterns\n- `clerk-orgs` - B2B multi-tenant organizations\n- `clerk-webhooks` - Webhook → database sync\n- `clerk-testing` - E2E testing setup\n- `clerk-swift` - Native iOS auth\n- `clerk-android` - Native Android auth\n- `clerk-expo` - Expo / React Native auth\n- `clerk-backend-api` - Backend REST API explorer\n\n## Documentation\n\n- **Quickstart Overview**: https://clerk.com/docs/getting-started/quickstart/overview\n- **Migration Guide**: https://clerk.com/docs/guides/development/migrating/overview\n- **Full Documentation**: https://clerk.com/docs\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}