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