clerk-setup

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. Quick Reference 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. See custom-ui/ → 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 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 (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 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 nextjs-patterns/references/middleware-strategies.md. shadcn/ui detected (components.json exists): ALWAYS apply the shadcn theme. See custom-ui/ → shadcn Theme section. 4. Get API Keys Two paths for development API keys: Keyless (Automatic) On first SDK initialization, Clerk auto-generates dev keys and shows "Claim your application" popover No manual key setup required—keys are created and injected automatically Simplest path for new projects Manual (Dashboard) Get keys from dashboard.clerk.com if Keyless doesn't trigger 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 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 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 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 , not wrapping : // root layout.tsx export default function RootLayout({ children }) { return ( {children} ) } Core 2 ONLY (skip if current SDK): ClerkProvider can wrap directly. Dynamic Rendering (Next.js) For dynamic rendering with auth data, use the dynamic prop: {children} 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: 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: npm install @clerk/ui import { shadcn } from '@clerk/ui/themes' <ClerkProvider appearance={{ theme: shadcn }}>{children} 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/themes and @clerk/themes/shadcn.css instead. Common Pitfalls 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 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) See Also custom-ui/ - Custom sign-in/up components webhooks/ - Webhook → database sync orgs/ - B2B multi-tenant organizations testing/ - E2E testing setup nextjs-patterns/ - Advanced Next.js patterns 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 Weekly Installs2.2KRepositoryclerk/skillsGitHub Stars25First SeenJan 30, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykWarnInstalled oncodex2.0Kopencode2.0Kgithub-copilot2.0Kgemini-cli2.0Kamp1.9Kkimi-cli1.9K