| name | clerk-install-auth |
| description | Install and configure Clerk SDK/CLI authentication.
Use when setting up a new Clerk integration, configuring API keys,
or initializing Clerk in your project.
Trigger with phrases like "install clerk", "setup clerk",
"clerk auth", "configure clerk API key", "add clerk to project".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep |
| version | 1.14.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","clerk","api","authentication"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Clerk Install & Auth
Overview
Set up Clerk SDK and configure authentication for Next.js, React, or Express. This skill covers SDK installation, environment variables, ClerkProvider, middleware, and initial auth verification.
Prerequisites
- Node.js 18+
- Package manager (npm, pnpm, or yarn)
- Clerk account at dashboard.clerk.com
- Publishable Key (
pk_test_*) and Secret Key (sk_test_*) from Clerk Dashboard > API Keys
Instructions
Step 1: Install SDK for Your Framework
set -euo pipefail
npm install @clerk/nextjs
npm install @clerk/clerk-react
npm install @clerk/express
npm install @clerk/backend
Step 2: Configure Environment Variables
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding
Ensure .env.local is in .gitignore:
echo ".env.local" >> .gitignore
Step 3: Add ClerkProvider (Next.js App Router)
import { ClerkProvider, SignInButton, SignedIn, SignedOut, UserButton } from '@clerk/nextjs'
import './globals.css'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider>
<html lang="en">
<body>
<header className="flex justify-between p-4">
<SignedOut>
<SignInButton />
</SignedOut>
<SignedIn>
<UserButton />
</SignedIn>
</header>
{children}
</body>
</html>
</ClerkProvider>
)
}
Step 4: Add Middleware
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isPublicRoute = createRouteMatcher([
'/',
'/sign-in(.*)',
'/sign-up(.*)',
'/api/webhooks(.*)',
])
export default clerkMiddleware(async (auth, req) => {
if (!isPublicRoute(req)) {
await auth.protect()
}
})
export const config = {
matcher: [
'/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
'/(api|trpc)(.*)',
],
}
Step 5: Create Sign-In and Sign-Up Pages
import { SignIn } from '@clerk/nextjs'
export default function SignInPage() {
return (
<div className="flex min-h-screen items-center justify-center">
<SignIn />
</div>
)
}
import { SignUp } from '@clerk/nextjs'
export default function SignUpPage() {
return (
<div className="flex min-h-screen items-center justify-center">
<SignUp />
</div>
)
}
Step 6: Verify Connection
import { auth } from '@clerk/nextjs/server'
export async function GET() {
const { userId } = await auth()
return Response.json({
clerkConnected: true,
authenticated: !!userId,
userId: userId || null,
})
}
React SPA Setup (Vite)
import { ClerkProvider } from '@clerk/clerk-react'
import App from './App'
const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
if (!PUBLISHABLE_KEY) {
throw new Error('Missing VITE_CLERK_PUBLISHABLE_KEY in .env')
}
ReactDOM.createRoot(document.getElementById('root')!).render(
<ClerkProvider publishableKey={PUBLISHABLE_KEY}>
<App />
</ClerkProvider>
)
Express Setup
import express from 'express'
import { clerkMiddleware, requireAuth, getAuth } from '@clerk/express'
const app = express()
app.use(clerkMiddleware())
app.get('/api/health', (req, res) => {
res.json({ status: 'ok' })
})
app.get('/api/profile', requireAuth(), (req, res) => {
const { userId } = getAuth(req)
res.json({ userId })
})
app.listen(3001, () => console.log('Server running on :3001'))
Error Handling
| Error | Cause | Solution |
|---|
Missing publishableKey | Env var not set | Add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY to .env.local |
ClerkProvider must wrap your application | Hook used outside provider | Ensure ClerkProvider wraps root layout |
auth() was called but Clerk can't detect clerkMiddleware() | Middleware not running | Place middleware.ts at project root, check matcher |
Module not found: @clerk/nextjs | Package not installed | Run npm install @clerk/nextjs |
| 500 error on all pages | CLERK_SECRET_KEY missing or wrong | Verify key prefix matches environment (sk_test_ for dev) |
Enterprise Considerations
- Use separate Clerk instances per environment (dev/staging/prod)
- Store keys in platform secrets (Vercel, AWS Secrets Manager), never in
.env files committed to git
- The
CLERK_SECRET_KEY must never be exposed client-side; only NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is safe for browsers
- For monorepos, install
@clerk/nextjs only in the app that needs it; use @clerk/backend for shared server packages
- Enable Clerk's "Enhanced email deliverability" in production for reliable transactional emails
Resources
Next Steps
Proceed to clerk-hello-world for your first authenticated request.
Output
- Installed Clerk SDK/packages for the target stack
- Auth routes/middleware wired and smoke-tested sign-in/sign-out
- Documented env vars and local-dev secrets posture (never commit real keys)
Examples
Fresh install on Next.js
User: Install Clerk auth from zero on this Next.js repo.
Skill: adds dependencies, env template, middleware, and a protected smoke route.
Repair a half-finished install
User: Clerk packages are present but middleware never runs.
Skill: fixes matcher config, provider placement, and env loading order.
