nextjs-integration

Instructions

This skill provides complete Clerk authentication integration for Next.js applications, supporting both App Router (Next.js 13+) and Pages Router patterns. It covers installation, middleware configuration, authentication helpers, and protected route patterns.

1. Clerk Installation & Setup

Install Clerk SDK and configure environment variables:

Run automated installation script

bash ./skills/nextjs-integration/scripts/install-clerk.sh

Or manually install

npm install @clerk/nextjs

Environment Variables:

Create .env.local with Clerk credentials

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here CLERK_SECRET_KEY=sk_test_your_key_here

Optional: Customize sign-in/sign-up URLs

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

What This Does:

• Installs @clerk/nextjs package

• Creates .env.local with placeholder keys

• Configures redirect URLs for sign-in/sign-up flows

• Sets up authentication endpoints

2. App Router Integration

Configure Clerk for Next.js App Router (13.4+):

Run App Router setup script

bash ./skills/nextjs-integration/scripts/setup-app-router.sh

Files Created:

• middleware.ts

• Route protection at edge

• app/layout.tsx

• ClerkProvider wrapper

• app/sign-in/[[...sign-in]]/page.tsx

• Sign-in page

• app/sign-up/[[...sign-up]]/page.tsx

• Sign-up page

App Router Features:

• Server Components with auth() helper

• Client Components with useAuth() hook

• Edge middleware for route protection

• Automatic session management

• RSC-compatible authentication

Copy Template Files:

Middleware configuration

cp ./skills/nextjs-integration/templates/app-router/middleware.ts ./middleware.ts

Root layout with ClerkProvider

cp ./skills/nextjs-integration/templates/app-router/layout.tsx ./app/layout.tsx

3. Pages Router Integration

Configure Clerk for Next.js Pages Router (12.x and earlier):

Run Pages Router setup script

bash ./skills/nextjs-integration/scripts/setup-pages-router.sh

Files Created:

• pages/_app.tsx

• ClerkProvider wrapper

• pages/api/auth.ts

• API route for auth callbacks

• pages/sign-in/[[...index]].tsx

• Sign-in page

• pages/sign-up/[[...index]].tsx

• Sign-up page

Pages Router Features:

• getServerSideProps with auth

• API routes with auth protection

• Client-side authentication hooks

• Custom sign-in/sign-up components

Copy Template Files:

_app.tsx with ClerkProvider

cp ./skills/nextjs-integration/templates/pages-router/_app.tsx ./pages/_app.tsx

Auth API route

cp ./skills/nextjs-integration/templates/pages-router/api/auth.ts ./pages/api/auth.ts

4. Authentication Middleware

Configure middleware for route protection:

Setup auth middleware with route matching

bash ./skills/nextjs-integration/scripts/configure-middleware.sh

Middleware Patterns:

• Protect specific routes (e.g., /dashboard/* )

• Public routes configuration

• API route protection

• Custom redirect logic

• Matcher configuration for edge runtime

Middleware Configuration:

// middleware.ts - Protects routes at the edge import { authMiddleware } from "@clerk/nextjs";

export default authMiddleware({ publicRoutes: ["/", "/api/public"], ignoredRoutes: ["/api/webhook"], });

export const config = { matcher: ['/((?!.+\.[\w]+$|_next).)', '/', '/(api|trpc)(.)'], };

5. Server Component Authentication (App Router)

Use auth() helper in Server Components:

import { auth } from '@clerk/nextjs';

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

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

// Protected server component logic const userData = await fetchUserData(userId);

return <div>Welcome {userData.name}</div>; }

Server-Side Helpers:

• auth()

• Get current user session

• currentUser()

• Get full user object

• redirectToSignIn()

• Redirect helper

• clerkClient

• Server-side Clerk API client

6. Client Component Authentication

Use React hooks in Client Components:

'use client'; import { useAuth, useUser } from '@clerk/nextjs';

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

if (!isLoaded) return <div>Loading...</div>; if (!isSignedIn) return <div>Please sign in</div>;

return <div>Hello {user.firstName}</div>; }

Client-Side Hooks:

• useAuth()

• Authentication state

• useUser()

• Current user data

• useClerk()

• Clerk instance methods

• useSignIn()

• Sign-in flow control

• useSignUp()

• Sign-up flow control

Examples

Example 1: Complete App Router Setup

1. Install Clerk

bash ./skills/nextjs-integration/scripts/install-clerk.sh

2. Configure App Router

bash ./skills/nextjs-integration/scripts/setup-app-router.sh

3. Setup middleware

bash ./skills/nextjs-integration/scripts/configure-middleware.sh

4. Copy protected route example

cp ./skills/nextjs-integration/examples/protected-route.tsx ./app/dashboard/page.tsx

5. Copy server component auth example

cp ./skills/nextjs-integration/examples/server-component-auth.tsx ./app/profile/page.tsx

6. Start development server

npm run dev

Result: Fully configured Next.js App Router with Clerk authentication, protected routes, and sign-in/sign-up pages

Example 2: Pages Router with API Routes

1. Install Clerk

bash ./skills/nextjs-integration/scripts/install-clerk.sh

2. Configure Pages Router

bash ./skills/nextjs-integration/scripts/setup-pages-router.sh

3. Copy API route template

cp ./skills/nextjs-integration/templates/pages-router/api/auth.ts ./pages/api/auth.ts

4. Test authentication

npm run dev

Result: Pages Router setup with API route authentication and custom auth pages

Example 3: Multi-Tenant Application

Configure organization-based authentication:

// Server Component with organization context import { auth } from '@clerk/nextjs';

export default async function TeamDashboard() { const { orgId, userId } = auth();

if (!orgId) { return <div>Please select an organization</div>; }

const teamData = await fetchTeamData(orgId); return <TeamView data={teamData} />; }

Organization Features:

• Multi-tenant support

• Organization switching

• Role-based access control

• Team member management

Example 4: Protected API Routes

// App Router API route with auth import { auth } from '@clerk/nextjs'; import { NextResponse } from 'next/server';

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

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

const data = await fetchProtectedData(userId); return NextResponse.json(data); }

Requirements

Dependencies:

• @clerk/nextjs

• Clerk Next.js SDK

• Next.js 12.0+ (Pages Router) or 13.4+ (App Router)

• React 18+

• Node.js 18.17+ or 20+

Clerk Account:

• Active Clerk application (free tier available)

• Publishable key and secret key from dashboard

• Configured sign-in/sign-up flows in Clerk dashboard

Project Structure:

• Next.js project initialized with create-next-app

• app/ directory (App Router) or pages/ directory (Pages Router)

• TypeScript recommended but not required

Environment Variables:

• .env.local for local development

• .env.production for production (never commit secrets)

• Vercel/deployment platform environment variable configuration

Security Best Practices

Never Hardcode API Keys:

✅ CORRECT - Use environment variables

CLERK_SECRET_KEY=your_clerk_secret_key_here

❌ WRONG - Never commit secrets

const clerkSecret = "sk_test_abc123..." // DON'T DO THIS

Protect Sensitive Routes:

• Use middleware for edge-level protection

• Validate auth in Server Components

• Check authentication in API routes

• Never trust client-side auth alone

Secure API Routes:

// Always validate auth server-side const { userId } = auth(); if (!userId) { return new NextResponse('Unauthorized', { status: 401 }); }

Environment Variable Management:

• Use .env.local for development (git-ignored)

• Use .env.example with placeholders (safe to commit)

• Store production keys in deployment platform

• Rotate keys periodically

App Router vs Pages Router

Use App Router When:

• Building new Next.js 13.4+ applications

• Need Server Components for better performance

• Want edge middleware capabilities

• Require streaming and suspense features

Use Pages Router When:

• Maintaining existing Next.js 12.x applications

• Team familiar with traditional Next.js patterns

• Need getServerSideProps/getStaticProps

• Gradual migration from older Next.js versions

Migration Path:

• Can mix both routers in same application

• Migrate routes incrementally

• App Router is recommended for new features

Integration Patterns

With Supabase:

• Use Clerk for authentication

• Pass Clerk user ID to Supabase RLS policies

• Sync user data between Clerk and Supabase

With tRPC:

• Add Clerk user context to tRPC context

• Protect procedures with auth middleware

• Type-safe authentication in API layer

With Prisma:

• Store Clerk user ID as foreign key

• Link user data to Clerk profiles

• Use userId for data isolation

With Vercel:

• Automatic environment variable sync

• Edge middleware deployment

• Preview deployments with auth

Troubleshooting

Middleware Not Running:

• Check matcher configuration in middleware.ts

• Ensure middleware.ts is at project root

• Verify Edge Runtime compatibility

Sign-In Redirect Loop:

• Check NEXT_PUBLIC_CLERK_SIGN_IN_URL matches route

• Verify publicRoutes includes sign-in page

• Ensure middleware doesn't protect auth routes

Server Component Hydration:

• Don't use useAuth in Server Components

• Use auth() helper instead

• Ensure ClerkProvider wraps layout

Environment Variables Not Loading:

• Restart development server after .env changes

• Use NEXT_PUBLIC_ prefix for client-side vars

• Check .env.local exists and is git-ignored

Plugin: clerk Version: 1.0.0 Category: Authentication Skill Type: Integration & Configuration