Clerk in Your App

Social Login#

Ever clicked "Sign in with Google" on a website? That's social login. Instead of making up yet another password, you use an account you already have.

Clerk makes social login easy. You flip it on in your Clerk dashboard, and people can log in with any of these.

• Google
• Apple
• GitHub
• Microsoft
• Many more

Using Clerk in Your Code#

Here's a simple example of Clerk in a Next.js app. You don't need to understand every lil detail yet... just notice how SHORT it is.

Setting It Up#

First, install Clerk's Next.js package from your project folder.

npm install @clerk/nextjs

Then make an app in the Clerk dashboard, copy your two keys from its API keys page, and paste them into a .env.local file in your project root.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

The secret key stays on the server, so never put it in a NEXT_PUBLIC_ variable. You'll also wrap your app in <ClerkProvider>, which happens in app/layout.tsx (the full file is down in Adding Login Buttons).

Protecting a Page#

Locking pages behind a login starts with Clerk's middleware file. It's called proxy.ts on Next.js 16 and newer, and middleware.ts on Next.js 15 and older (the code inside is the same either way).

// proxy.ts (or middleware.ts on Next.js 15 and older)
import { clerkMiddleware } from '@clerk/nextjs/server'
 
export default clerkMiddleware()
 
export const config = {
  matcher: [
    // Skip Next.js internals and 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)(.*)',
    // Always run for Clerk's own routes
    '/__clerk/(.*)',
  ],
}

That gets Clerk running on every request. Heads up though, on its own it doesn't lock anything. Every route stays public until you add a check.

And Clerk's advice now is to put that check right on the page (or API route) that reads the private data, not in the middleware. One line does it.

// app/dashboard/page.tsx
import { auth } from '@clerk/nextjs/server'
 
export default async function Dashboard() {
  // Sends anyone who isn't logged in to the sign-in page
  await auth.protect()
 
  return <h1>Your dashboard</h1>
}

Do that on every page and API route that touches private stuff. (you'll see older tutorials protect routes in middleware with createRouteMatcher, but Clerk has deprecated that now)

Getting the Current User#

Once someone's logged in, you can find out who they are.

import { currentUser } from '@clerk/nextjs/server'
 
export default async function Dashboard() {
  const user = await currentUser()
 
  if (!user) return <h1>You're not logged in</h1>
 
  return <h1>Welcome, {user.firstName}!</h1>
}

Clerk hands you info like this.

• User's name
• Email address
• Profile picture
• User ID (a unique identifier)

Adding Login Buttons#

Clerk also ships ready-made components, so you're not building buttons from scratch. They go in your root layout, inside the <ClerkProvider> that every Clerk app needs.

// app/layout.tsx
import { ClerkProvider, SignInButton, SignUpButton, UserButton, Show } from '@clerk/nextjs'
import './globals.css'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClerkProvider>
          <header>
            <Show when="signed-out">
              <SignInButton />  {/* Opens the login form */}
              <SignUpButton />  {/* Opens the signup form */}
            </Show>
            <Show when="signed-in">
              <UserButton />    {/* User menu once they're logged in */}
            </Show>
          </header>
          {children}
        </ClerkProvider>
      </body>
    </html>
  )
}

Run npm run dev, click Sign up, and you've got a working login. Clerk's Next.js quickstart has the same steps if you want to double check anything.