npx skills add ...
npx skills add clerk/skills --skill clerk-setup
npx skills add clerk/skills --skill clerk-setup
Add Clerk authentication to any project by following the official quickstart
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. For agents, the clerk CLI handles most of this end to end — see the next section.
The clerk CLI replaces most Dashboard clicks. Three scenarios cover almost everything:
clerk init creates the Clerk app via PLAPI, links the project, writes the framework-specific publishable + secret keys to the right env file (e.g. .env.local for Next.js, .env for Vite-based projects), and installs the SDK package.
PLAPI exposes secret-key rotation directly. Use raw clerk api until the friendly wrapper ships:
delay_old_secrets_expiration_hours keeps the old key valid for the grace period so deploys can roll forward without downtime.
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.--json on apps list/create, users create, and doctor for parseable output.VITE_CLERK_PUBLISHABLE_KEY for Vite, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY for Next.js, etc.) and target file (.env.development.local > .env.local > .env).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 |
If the project has
components.json(shadcn/ui), apply the shadcn theme after setup. Seeclerk-custom-uiskill → 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 (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:
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/quickstartRead the project's package.json and match dependencies to the table above.
Use WebFetch to retrieve the official quickstart for the detected framework:
Execute each step from the quickstart guide:
Next.js: Create
proxy.ts(Next.js <=15:middleware.ts). See theclerk-nextjs-patternsskill for middleware strategies.
shadcn/ui detected (
components.jsonexists): ALWAYS apply the shadcn theme. Seeclerk-custom-uiskill → 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>:
Core 2 ONLY (skip if current SDK):
ClerkProvidercan wrap<html>directly.
For dynamic rendering with auth data, use the dynamic prop:
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:
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:
Also import the shadcn CSS in your global styles:
Core 2 ONLY (skip if current SDK): Import from
@clerk/themesand@clerk/themes/shadcn.cssinstead.
Run
clerk doctorfirst. 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: ['/((?!.\.. |
| 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: ['/((?!.\.. |
| 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) |
clerk-custom-ui - Custom sign-in/up componentsclerk-nextjs-patterns - Advanced Next.js patternsclerk-react-patterns - React SPA patternsclerk-react-router-patterns - React Router patternsclerk-vue-patterns - Vue patternsclerk-nuxt-patterns - Nuxt patternsclerk-astro-patterns - Astro patternsclerk-tanstack-patterns - TanStack Start patternsclerk-chrome-extension-patterns - Chrome Extension patternsclerk-orgs - B2B multi-tenant organizationsclerk-webhooks - Webhook → database syncclerk-testing - E2E testing setupclerk-swift - Native iOS authclerk-android - Native Android authclerk-expo - Expo / React Native authclerk-backend-api - Backend REST API explorerclerk 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 varsclerk auth login
clerk apps create "My App" --json # returns the new app_id
clerk link --app app_xxx
clerk env pullclerk env pull # refresh keys (uses linked profile)
clerk env pull --instance prod # production keys
clerk doctor --json # framework integration health checkclerk api --platform POST /v1/platform/applications/<app_id>/rotate_secret_keys \
-d '{"delay_old_secrets_expiration_hours": 24, "reason": "scheduled rotation"}'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)WebFetch: https://clerk.com/docs/{framework}/getting-started/quickstart
Prompt: "Extract the complete setup instructions including all code snippets, file paths, and configuration steps."// root layout.tsx
export default function RootLayout({ children }) {
return (
<html>
<body>
<ClerkProvider>{children}</ClerkProvider>
</body>
</html>
)
}<ClerkProvider dynamic>{children}</ClerkProvider>npm install @clerk/uinpm install @clerk/uiimport { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';