Provides Clerk updates since training cutoff: Core 3 SDKs for React/Next.js, Go/Python SDKs, <Show> component, Clerk Elements, billing APIs, machine auth. Load before Clerk tasks.
npx claudepluginhub nevaberry/nevaberry-plugins --plugin clerk-knowledge-patchThis skill uses the workspace's default tool permissions.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Implements structured self-debugging workflow for AI agent failures: capture errors, diagnose patterns like loops or context overflow, apply contained recoveries, and generate introspection reports.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Claude's baseline knowledge covers Clerk through Core 2 (@clerk/nextjs v5, @clerk/clerk-react). This patch adds Core 3 changes (@clerk/nextjs v6+, @clerk/react v1+), Go SDK v2, Python backend SDK, and new features through early 2025.
| Topic | Reference | Key Content |
|---|---|---|
| Components | references/components.md | <Show> (replaces SignedIn/SignedOut), UserAvatar, Waitlist, billing components, UserButton menu customization, UNSAFE_PortalProvider |
| Authentication Flows | references/authentication-flows.md | Core 3 custom flow API (method chaining), reverification, session tasks, signUpIfMissing, Errors<T> type, session token v2 claims |
| Middleware & Backend | references/middleware-backend.md | isAuthenticated, async clerkClient(), machine token auth, Frontend API proxy, dynamic keys, organizationSyncOptions |
| Organizations & Permissions | references/organizations.md | Role Sets, system permissions, org slug URL patterns |
| Clerk Elements | references/clerk-elements.md | Headless UI primitives (@clerk/elements), sign-in/sign-up anatomy, shadcn/ui CLI |
| Billing | references/billing.md | Custom checkout (useCheckout + PaymentElement), billing hooks, backend/client-side billing APIs, B2B billing, free trials |
| Go SDK v2 | references/go-sdk.md | Package structure, sub-package imports, HTTP middleware, JWT verification, reverification, testing patterns |
| Python SDK | references/python-sdk.md | clerk-backend-api package, _async suffix convention, request authentication |
| Integrations & Utilities | references/integrations-utilities.md | MCP tools, OAuth provider (IdP), TanStack Start, React Router, Astro, Chrome Extension, getToken, ClerkOfflineError, Web3, enterprise_sso |
# React SDK renamed
npm install @clerk/react # was @clerk/clerk-react
# Next.js unchanged
npm install @clerk/nextjs # still @clerk/nextjs (now v6+)
<Show> Replaces <SignedIn> / <SignedOut>import { Show, SignInButton, UserButton } from '@clerk/react'
<Show when="signed-in">
<UserButton />
</Show>
<Show when="signed-out">
<SignInButton />
</Show>
// Authorization checks
<Show when={{ permission: 'org:invoices:create' }} fallback={<p>No access</p>}>
<InvoiceForm />
</Show>
<Show when={{ feature: 'premium_access' }} fallback={<p>Upgrade</p>}>
<PremiumFeature />
</Show>
<Show when={(has) => has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })}>
<SettingsPage />
</Show>
Full when type: 'signed-in' | 'signed-out' | { feature: string } | { permission: string } | { plan: string } | { role: string } | (has) => boolean
| Core 2 | Core 3 | Notes |
|---|---|---|
<SignedIn> / <SignedOut> | <Show when="signed-in"> | Unified control component |
@clerk/clerk-react | @clerk/react | Package rename |
if (!userId) | if (!isAuthenticated) | auth() returns isAuthenticated boolean |
const client = clerkClient | const client = await clerkClient() | Now async function |
signUp.create() → prepareVerification() → attemptVerification() → setActive() | signUp.password() → verifications.sendEmailCode() → verifications.verifyEmailCode() → finalize() | Method chaining API |
clerkJSVariant: 'headless' | prefetchUI={false} | On ClerkProvider |
saml strategy | enterprise_sso | Supports both SAML + OIDC |
user.samlAccounts | user.enterpriseAccounts | Property rename |
clerkClient.samlConnections | clerkClient.enterpriseConnections | Backend rename |
ClerkProvider Auto-detects Key// No publishableKey prop needed — reads from env vars automatically:
// NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (Next.js)
// VITE_CLERK_PUBLISHABLE_KEY (Vite)
// CLERK_PUBLISHABLE_KEY (general)
<ClerkProvider>
<App />
</ClerkProvider>
import { auth } from '@clerk/nextjs/server'
// Core 3 pattern
const { isAuthenticated, userId, redirectToSignIn } = await auth()
if (!isAuthenticated) return redirectToSignIn()
// clerkClient is now async
const client = await clerkClient()
const user = await client.users.getUser(userId)
// Middleware — protect routes by token type
export default clerkMiddleware(async (auth, req) => {
if (isApiRoute(req)) await auth.protect({ token: 'api_key' })
if (isM2MRoute(req)) await auth.protect({ token: 'm2m_token' })
if (isOAuthRoute(req)) await auth.protect({ token: 'oauth_token' })
})
// Route handler — acceptsToken parameter
const { userId } = await auth({ acceptsToken: 'oauth_token' })
getToken()import { getToken } from '@clerk/nextjs' // or @clerk/react, @clerk/vue
// Works outside React — in axios interceptors, React Query, vanilla JS
axios.interceptors.request.use(async (config) => {
const token = await getToken()
if (token) config.headers.Authorization = `Bearer ${token}`
return config
})
Throws ClerkOfflineError when offline (instead of returning null). Import from @clerk/react/errors.
import type { UserResource, OrganizationResource } from '@clerk/react/types'
// Also: @clerk/nextjs/types, @clerk/vue/types, etc.
Old pattern: signUp.create() → prepareEmailAddressVerification() → attemptEmailAddressVerification() → setActive()
New pattern uses method chaining:
// Sign-up
const { signUp, errors, fetchStatus } = useSignUp()
await signUp.password({ emailAddress, password })
await signUp.verifications.sendEmailCode()
await signUp.verifications.verifyEmailCode({ code })
if (signUp.status === 'complete') await signUp.finalize({ navigate: ({ decorateUrl }) => { /* ... */ } })
// Sign-in
const { signIn, errors, fetchStatus } = useSignIn()
await signIn.create({ identifier: emailAddress })
await signIn.emailCode.sendCode()
await signIn.emailCode.verifyCode({ code })
if (signIn.status === 'complete') await signIn.finalize({ navigate: ({ decorateUrl }) => { /* ... */ } })
Field-level errors: errors.fields.emailAddress, errors.fields.password, errors.fields.code. Loading: fetchStatus === 'fetching'.
// Server action
import { auth, reverificationError } from '@clerk/nextjs/server'
export const sensitiveAction = async () => {
const { has } = await auth.protect()
if (!has({ reverification: 'strict' })) return reverificationError('strict')
// Presets: 'strict_mfa' | 'strict' (10m) | 'moderate' (1h) | 'lax'
}
// Client — wraps action, auto-shows verification modal
import { useReverification } from '@clerk/nextjs'
const perform = useReverification(sensitiveAction)
const result = await perform() // null if user cancelled
Three states: signed-in | pending | signed-out. Pending = authenticated but tasks incomplete (choose org, reset password, setup MFA).
import { TaskChooseOrganization, TaskResetPassword, TaskSetupMFA } from '@clerk/nextjs'
// In middleware — redirect pending users
const { isAuthenticated, sessionStatus } = await auth()
if (!isAuthenticated && sessionStatus === 'pending') {
// redirect to /session-tasks
}
// Access pending user data
const { userId } = await auth({ treatPendingAsSignedOut: false })
// Components (PricingTable from main, rest from /experimental)
import { PricingTable } from '@clerk/nextjs'
import { CheckoutButton, useCheckout, usePlans, useSubscription } from '@clerk/nextjs/experimental'
<PricingTable /> // works signed-in or signed-out
<PricingTable for="organization" /> // org-level plans
<CheckoutButton planId="cplan_xxx" planPeriod="month" for="user" /> // must be in <Show when="signed-in">
// Hooks (all experimental) — shared interface: { data, isLoading, hasNextPage, fetchNext, revalidate }
const { data: plans } = usePlans({ for: 'user' })
const { data: subscription } = useSubscription({ for: 'organization' })
// Backend
const client = await clerkClient()
const sub = await client.billing.getUserBillingSubscription('user_123')
await client.billing.cancelSubscriptionItem('subi_123', { endNow: true })
B2B gotcha: has({ permission: 'org:teams:manage' }) returns false if the org's Plan doesn't include the "teams" Feature, even if the user has the permission.
import "github.com/clerk/clerk-sdk-go/v2" // was github.com/clerkinc/clerk-sdk-go
import "github.com/clerk/clerk-sdk-go/v2/user" // sub-packages per resource
import clerkhttp "github.com/clerk/clerk-sdk-go/v2/http"
clerk.SetKey("sk_live_XXX")
// Pointer helpers: clerk.String(), clerk.Bool(), clerk.Int64()
// Header-only auth (no cookies): clerkhttp.RequireHeaderAuthorization()(handler)
// Claims: claims, ok := clerk.SessionClaimsFromContext(r.Context())
# Package: clerk-backend-api (NOT clerk-python)
from clerk_backend_api import Clerk
with Clerk(bearer_auth="sk_live_xxx") as clerk:
user = clerk.users.get(user_id="user_123")
# Async uses _async suffix: await clerk.users.get_async(user_id="user_123")