Vibeship-spawner-skills clerk-auth

Clerk Authentication Skill

install

source · Clone the upstream repo

git clone https://github.com/vibeforge1111/vibeship-spawner-skills

manifest: integrations/clerk-auth/skill.yaml

Clerk Authentication Skill

Patterns for authentication, user management, and multi-tenancy

id: clerk-auth name: Clerk Authentication display_name: Clerk Authentication description: Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync version: 1.0.0 category: integrations tags:

clerk
authentication
auth
user-management
multi-tenancy
organizations
sso
oauth

triggers:

"adding authentication"
"clerk auth"
"user authentication"
"sign in"
"sign up"
"user management"
"multi-tenancy"
"organizations"
"sso"
"single sign-on"

capabilities:

"Next.js App Router integration"
"Middleware route protection"
"Organizations and multi-tenancy"
"Webhook user sync with database"
"Server Component authentication"
"Client Component hooks"
"Enterprise SSO (SAML, OIDC)"
"Role-based access control"

patterns:

id: nextjs-app-router-setup name: Next.js App Router Setup description: | Complete Clerk setup for Next.js 14/15 App Router.

Includes ClerkProvider, environment variables, and basic sign-in/sign-up components.

Key components:
- ClerkProvider: Wraps app for auth context
- <SignIn />, <SignUp />: Pre-built auth forms
- <UserButton />: User menu with session management
code_example: |

Environment variables (.env.local)

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

// app/layout.tsx import { ClerkProvider } from '@clerk/nextjs';

export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( <ClerkProvider> <html lang="en"> <body>{children}</body> </html> </ClerkProvider> ); }

// app/sign-in/[[...sign-in]]/page.tsx import { SignIn } from '@clerk/nextjs';

export default function SignInPage() { return ( <div className="flex justify-center items-center min-h-screen"> <SignIn /> </div> ); }

// app/sign-up/[[...sign-up]]/page.tsx import { SignUp } from '@clerk/nextjs';

export default function SignUpPage() { return ( <div className="flex justify-center items-center min-h-screen"> <SignUp /> </div> ); }

// components/Header.tsx import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs';

export function Header() { return ( <header className="flex justify-between p-4"> <h1>My App</h1> <SignedOut> <SignInButton /> </SignedOut> <SignedIn> <UserButton afterSignOutUrl="/" /> </SignedIn> </header> ); }

anti_patterns:
- pattern: "ClerkProvider inside page component" why: "Provider must wrap entire app in root layout" fix: "Move ClerkProvider to app/layout.tsx"
- pattern: "Using auth() without middleware" why: "auth() requires clerkMiddleware to be configured" fix: "Set up middleware.ts with clerkMiddleware"
references:
- "https://clerk.com/docs/nextjs/getting-started/quickstart"
id: middleware-protection name: Middleware Route Protection description: | Protect routes using clerkMiddleware and createRouteMatcher.

Best practices:
- Single middleware.ts file at project root
- Use createRouteMatcher for route groups
- auth.protect() for explicit protection
- Centralize all auth logic in middleware
code_example: | // middleware.ts import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

// Define protected route patterns const isProtectedRoute = createRouteMatcher([ '/dashboard(.)', '/settings(.)', '/api/private(.*)', ]);

// Define public routes (optional, for clarity) const isPublicRoute = createRouteMatcher([ '/', '/sign-in(.)', '/sign-up(.)', '/api/webhooks(.*)', ]);

export default clerkMiddleware(async (auth, req) => { // Protect matched routes if (isProtectedRoute(req)) { await auth.protect(); } });

export const config = { matcher: [ // Match all routes except static files '/((?!_next|[^?]\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).)', // Always run for API routes '/(api|trpc)(.*)', ], };

// Advanced: Role-based protection export default clerkMiddleware(async (auth, req) => { if (isProtectedRoute(req)) { await auth.protect(); }
```
// Admin routes require admin role
if (req.nextUrl.pathname.startsWith('/admin')) {
  await auth.protect({
    role: 'org:admin',
  });
}

// Premium routes require premium permission
if (req.nextUrl.pathname.startsWith('/premium')) {
  await auth.protect({
    permission: 'org:premium:access',
  });
}
```
});

anti_patterns:
- pattern: "Multiple middleware.ts files" why: "Causes conflicts and redirect loops" fix: "Use single middleware.ts with route matchers"
- pattern: "Manual redirects in components" why: "Double redirects, missed routes" fix: "Handle all redirects in middleware"
- pattern: "Missing matcher config" why: "Middleware won't run on all routes" fix: "Add comprehensive matcher pattern"
references:
- "https://clerk.com/docs/reference/nextjs/clerk-middleware"

id: server-component-auth name: Server Component Authentication description: | Access auth state in Server Components using auth() and currentUser().

Key functions:

auth(): Returns userId, sessionId, orgId, claims
currentUser(): Returns full User object
Both require clerkMiddleware to be configured

code_example: | // app/dashboard/page.tsx (Server Component) import { auth, currentUser } from '@clerk/nextjs/server'; import { redirect } from 'next/navigation';

export default async function DashboardPage() { const { userId } = await auth();

if (!userId) {
  redirect('/sign-in');
}

// Full user data (counts toward rate limits)
const user = await currentUser();

return (
  <div>
    <h1>Welcome, {user?.firstName}!</h1>
    <p>Email: {user?.emailAddresses[0]?.emailAddress}</p>
  </div>
);

}

// Using auth() for quick checks export default async function ProtectedLayout({ children, }: { children: React.ReactNode; }) { const { userId, orgId, orgRole } = await auth();

if (!userId) {
  redirect('/sign-in');
}

// Check organization access
if (!orgId) {
  redirect('/select-org');
}

return (
  <div>
    <p>Organization Role: {orgRole}</p>
    {children}
  </div>
);

}

// Server Action with auth check // app/actions/posts.ts 'use server'; import { auth } from '@clerk/nextjs/server';

export async function createPost(formData: FormData) { const { userId } = await auth();

if (!userId) {
  throw new Error('Unauthorized');
}

const title = formData.get('title') as string;

// Create post with userId
const post = await prisma.post.create({
  data: {
    title,
    authorId: userId,
  },
});

return post;

}

anti_patterns:

pattern: "Not awaiting auth()" why: "auth() is async in App Router" fix: "Use await auth() or const { userId } = await auth()"
pattern: "Using currentUser() for simple checks" why: "Counts toward rate limits, slower than auth()" fix: "Use auth() for userId checks, currentUser() for user data"

references:

"https://clerk.com/docs/references/nextjs/auth"

id: client-component-hooks name: Client Component Hooks description: | Access auth state in Client Components using hooks.

Key hooks:

useUser(): User object and loading state
useAuth(): Auth state, signOut, etc.
useSession(): Session object
useOrganization(): Current organization

code_example: | // components/UserProfile.tsx 'use client'; import { useUser, useAuth } from '@clerk/nextjs';

export function UserProfile() { const { user, isLoaded, isSignedIn } = useUser(); const { signOut } = useAuth();

if (!isLoaded) {
  return <div>Loading...</div>;
}

if (!isSignedIn) {
  return <div>Not signed in</div>;
}

return (
  <div>
    <img src={user.imageUrl} alt={user.fullName ?? ''} />
    <h2>{user.fullName}</h2>
    <p>{user.emailAddresses[0]?.emailAddress}</p>
    <button onClick={() => signOut()}>Sign Out</button>
  </div>
);

}

// Organization context 'use client'; import { useOrganization, useOrganizationList } from '@clerk/nextjs';

export function OrgSwitcher() { const { organization, membership } = useOrganization(); const { setActive, userMemberships } = useOrganizationList({ userMemberships: { infinite: true }, });

if (!organization) {
  return <p>No organization selected</p>;
}

return (
  <div>
    <p>Current: {organization.name}</p>
    <p>Role: {membership?.role}</p>

    <select
      onChange={(e) => setActive?.({ organization: e.target.value })}
      value={organization.id}
    >
      {userMemberships.data?.map((mem) => (
        <option key={mem.organization.id} value={mem.organization.id}>
          {mem.organization.name}
        </option>
      ))}
    </select>
  </div>
);

}

// Protected client component 'use client'; import { useAuth } from '@clerk/nextjs'; import { useRouter } from 'next/navigation'; import { useEffect } from 'react';

export function ProtectedContent() { const { isLoaded, userId } = useAuth(); const router = useRouter();

useEffect(() => {
  if (isLoaded && !userId) {
    router.push('/sign-in');
  }
}, [isLoaded, userId, router]);

if (!isLoaded || !userId) {
  return <div>Loading...</div>;
}

return <div>Protected content here</div>;

}

anti_patterns:

pattern: "Not checking isLoaded" why: "Auth state undefined during hydration" fix: "Always check isLoaded before accessing user/auth state"
pattern: "Using hooks in Server Components" why: "Hooks only work in Client Components" fix: "Use auth() and currentUser() in Server Components"

references:

"https://clerk.com/docs/references/react/use-user"

id: organizations-multi-tenancy name: Organizations and Multi-Tenancy description: | Implement B2B multi-tenancy with Clerk Organizations.

Features:
- Multiple orgs per user
- Roles and permissions
- Organization-scoped data
- Enterprise SSO per organization
code_example: | // Organization creation UI // app/create-org/page.tsx import { CreateOrganization } from '@clerk/nextjs';

export default function CreateOrgPage() { return ( <div className="flex justify-center"> <CreateOrganization afterCreateOrganizationUrl="/dashboard" /> </div> ); }

// Organization profile and management // app/org-settings/page.tsx import { OrganizationProfile } from '@clerk/nextjs';

export default function OrgSettingsPage() { return <OrganizationProfile />; }

// Organization switcher in header // components/Header.tsx import { OrganizationSwitcher, UserButton } from '@clerk/nextjs';

export function Header() { return ( <header className="flex justify-between p-4"> <OrganizationSwitcher hidePersonal afterCreateOrganizationUrl="/dashboard" afterSelectOrganizationUrl="/dashboard" /> <UserButton /> </header> ); }

// Org-scoped data access // app/dashboard/page.tsx import { auth } from '@clerk/nextjs/server'; import { prisma } from '@/lib/prisma';

export default async function DashboardPage() { const { orgId } = await auth();
```
if (!orgId) {
  redirect('/select-org');
}

// Fetch org-scoped data
const projects = await prisma.project.findMany({
  where: { organizationId: orgId },
});

return (
  <div>
    <h1>Projects</h1>
    {projects.map((p) => (
      <div key={p.id}>{p.name}</div>
    ))}
  </div>
);
```
}

// Role-based UI 'use client'; import { useOrganization, Protect } from '@clerk/nextjs';

export function AdminPanel() { const { membership } = useOrganization();
```
// Using Protect component
return (
  <Protect role="org:admin" fallback={<p>Admin access required</p>}>
    <div>Admin content here</div>
  </Protect>
);

// Or manual check
if (membership?.role !== 'org:admin') {
  return <p>Admin access required</p>;
}

return <div>Admin content here</div>;
```
}

anti_patterns:
- pattern: "Not scoping data by orgId" why: "Data leaks between organizations" fix: "Always filter queries by orgId from auth()"
- pattern: "Hardcoding role strings" why: "Typos cause access issues" fix: "Define role constants or use TypeScript enums"
references:
- "https://clerk.com/docs/guides/organizations"
- "https://clerk.com/articles/multi-tenancy-in-react-applications-guide"

id: webhook-user-sync name: Webhook User Sync description: | Sync Clerk users to your database using webhooks.

Key webhooks:

user.created: New user signed up
user.updated: User profile changed
user.deleted: User deleted account

Uses svix for signature verification.

code_example: | // app/api/webhooks/clerk/route.ts import { Webhook } from 'svix'; import { headers } from 'next/headers'; import { WebhookEvent } from '@clerk/nextjs/server'; import { prisma } from '@/lib/prisma';

export async function POST(req: Request) { const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;

if (!WEBHOOK_SECRET) {
  throw new Error('Missing CLERK_WEBHOOK_SECRET');
}

// Get headers
const headerPayload = await headers();
const svix_id = headerPayload.get('svix-id');
const svix_timestamp = headerPayload.get('svix-timestamp');
const svix_signature = headerPayload.get('svix-signature');

if (!svix_id || !svix_timestamp || !svix_signature) {
  return new Response('Missing svix headers', { status: 400 });
}

// Get body
const payload = await req.json();
const body = JSON.stringify(payload);

// Verify webhook
const wh = new Webhook(WEBHOOK_SECRET);
let evt: WebhookEvent;

try {
  evt = wh.verify(body, {
    'svix-id': svix_id,
    'svix-timestamp': svix_timestamp,
    'svix-signature': svix_signature,
  }) as WebhookEvent;
} catch (err) {
  console.error('Webhook verification failed:', err);
  return new Response('Verification failed', { status: 400 });
}

// Handle events
const eventType = evt.type;

if (eventType === 'user.created') {
  const { id, email_addresses, first_name, last_name, image_url } = evt.data;

  await prisma.user.create({
    data: {
      clerkId: id,
      email: email_addresses[0]?.email_address,
      firstName: first_name,
      lastName: last_name,
      imageUrl: image_url,
    },
  });
}

if (eventType === 'user.updated') {
  const { id, email_addresses, first_name, last_name, image_url } = evt.data;

  await prisma.user.update({
    where: { clerkId: id },
    data: {
      email: email_addresses[0]?.email_address,
      firstName: first_name,
      lastName: last_name,
      imageUrl: image_url,
    },
  });
}

if (eventType === 'user.deleted') {
  const { id } = evt.data;

  await prisma.user.delete({
    where: { clerkId: id! },
  });
}

return new Response('Webhook processed', { status: 200 });

}

// Prisma schema // prisma/schema.prisma model User { id String @id @default(cuid()) clerkId String @unique email String @unique firstName String? lastName String? imageUrl String? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt

posts     Post[]
@@index([clerkId])

}

anti_patterns:

pattern: "Not verifying webhook signature" why: "Anyone can hit your endpoint with fake data" fix: "Always verify with svix"
pattern: "Blocking middleware for webhook routes" why: "Webhooks come from Clerk, not authenticated users" fix: "Add /api/webhooks(.*)' to public routes"
pattern: "Not handling race conditions" why: "user.created might arrive after user.updated" fix: "Use upsert instead of create, handle missing records"

references:

id: api-route-protection name: API Route Protection description: | Protect API routes using auth() from Clerk.

Route Handlers in App Router use auth() for authentication. Middleware provides initial protection, auth() provides in-handler verification.

code_example: | // app/api/projects/route.ts import { auth } from '@clerk/nextjs/server'; import { prisma } from '@/lib/prisma'; import { NextResponse } from 'next/server';

export async function GET() { const { userId, orgId } = await auth();

if (!userId) {
  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}

// User's personal projects or org projects
const projects = await prisma.project.findMany({
  where: orgId
    ? { organizationId: orgId }
    : { userId, organizationId: null },
});

return NextResponse.json(projects);

}

export async function POST(req: Request) { const { userId, orgId } = await auth();

if (!userId) {
  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}

const body = await req.json();

const project = await prisma.project.create({
  data: {
    name: body.name,
    userId,
    organizationId: orgId ?? null,
  },
});

return NextResponse.json(project, { status: 201 });

}

// Protected with role check // app/api/admin/users/route.ts export async function GET() { const { userId, orgRole } = await auth();

if (!userId) {
  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}

if (orgRole !== 'org:admin') {
  return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
}

// Admin-only logic
const users = await prisma.user.findMany();
return NextResponse.json(users);

}

// Using getAuth in older patterns (not recommended) // For backwards compatibility only import { getAuth } from '@clerk/nextjs/server';

export async function GET(req: Request) { const { userId } = getAuth(req); // ... }

anti_patterns:

pattern: "Trusting middleware alone" why: "Middleware can be bypassed (CVE-2025-29927)" fix: "Always verify auth in route handler too"
pattern: "Not checking orgId for multi-tenant" why: "Users might access other org's data" fix: "Always filter by orgId from auth()"

references:

"https://clerk.com/docs/guides/protecting-pages"

handoff_triggers:

condition: "needs database" target_skill: postgres-wizard context: "User data storage with Prisma"
condition: "needs search" target_skill: algolia-search context: "Secured API keys per user"
condition: "needs payments" target_skill: stripe-integration context: "Customer ID linked to Clerk userId"
condition: "needs analytics" target_skill: segment-cdp context: "User identification and tracking"

Vibeship-spawner-skills clerk-auth

Clerk Authentication Skill

Patterns for authentication, user management, and multi-tenancy

Environment variables (.env.local)