### Development Environment Setup

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

Steps to set up the development environment, including cloning the repository, installing dependencies, configuring environment variables, and running the development server.

```text
Development:
  1. Clone repo
  2. pnpm install
  3. Create .env.local with Clerk API keys
  4. pnpm dev (starts on port 3000)
  5. Navigate to http://localhost:3000
  6. Click "Sign In" or "Sign Up"
  7. Follow Clerk authentication flow
  8. Redirected to home page with UserButton visible

```

--------------------------------

### Clerk Next.js App Setup Steps

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

A step-by-step guide to setting up a new Next.js project with Clerk authentication, including cloning the repository, installing dependencies, and configuring environment variables.

```bash
# 1. Get Clerk API keys from https://dashboard.clerk.com/~/api-keys

# 2. Clone repo
git clone https://github.com/clerk/clerk-nextjs-app-quickstart
cd clerk-nextjs-app-quickstart

# 3. Install dependencies
pnpm install

# 4. Create .env.local with Clerk keys
cp .env.example .env.local
# Then edit .env.local with your keys

# 5. Start dev server
pnpm dev
# Open http://localhost:3000
```

--------------------------------

### Start Production Server with pnpm

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Run this command to start the production server after installation and setup. This is typically used for deploying or testing the live application.

```bash
pnpm start
```

--------------------------------

### Copy Environment Example File

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Create a local environment file by copying the example configuration file. This is the first step before adding your Clerk API keys.

```bash
cp .env.example .env.local
```

--------------------------------

### Build and Start Production Server

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Commands to build the Next.js application for production and start a local server to test the production build.

```bash
pnpm build
pnpm start
```

--------------------------------

### Clerk Setup and Development Commands

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Provides essential commands for setting up Clerk authentication in a Next.js project and managing the development environment. This includes installing dependencies, starting the development server, and configuring environment variables with API keys.

```bash
# Development
pnpm install              # Install dependencies
pnpm dev                  # Start dev server
pnpm build                # Build for production
pnpm start                # Run production build
pnpm lint                 # Check code quality

# Git
git clone <url>           # Clone repo
git add -A                # Stage all changes
git commit -m "msg"       # Create commit
git push                  # Push to GitHub

# Clerk Setup
# 1. Get keys from https://dashboard.clerk.com/~/api-keys
# 2. cp .env.example .env.local
# 3. Edit .env.local with your keys
# 4. pnpm dev

```

--------------------------------

### Clone the Quickstart Repository

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/README.md

Clone the official Clerk Next.js App Router quickstart repository to your local machine.

```bash
git clone https://github.com/clerk/clerk-nextjs-app-quickstart
```

--------------------------------

### Complete Header Example in Root Layout

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/components.md

This example demonstrates a complete header implementation in the root layout, showing sign-in/sign-up buttons when the user is signed out and the user button when the user is signed in.

```typescript
<header>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <UserButton />
  </Show>
</header>
```

--------------------------------

### Install Dependencies

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/README.md

Install the necessary project dependencies using pnpm. A --force flag might be required due to React release candidates.

```bash
pnpm install
```

--------------------------------

### Install Prisma Client and Prisma CLI

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Install the necessary packages for Prisma ORM. This includes the client for database interactions and the CLI for migrations and schema management.

```bash
pnpm add @prisma/client
pnpm add -D prisma
```

--------------------------------

### Clone the Clerk Next.js Quickstart Repository

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Use this command to clone the official Clerk Next.js application quickstart repository to your local machine.

```bash
git clone https://github.com/clerk/clerk-nextjs-app-quickstart.git
cd clerk-nextjs-app-quickstart
```

--------------------------------

### Start the Next.js Development Server

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Launch the development server for your Next.js application using pnpm. This command will build the application and start a local server, typically at http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### Production Environment Setup on Vercel

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

Instructions for deploying the application to Vercel, including setting environment variables and leveraging Vercel's automatic build and deployment process.

```text
Production (Vercel):
  1. Deploy repo to Vercel
  2. Set environment variables in Vercel dashboard
  3. Vercel automatically detects Next.js
  4. Builds and deploys automatically

```

--------------------------------

### Project Structure

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/overview.md

Overview of the file and directory structure for the Clerk Next.js App Router quickstart.

```tree
clerk-nextjs-app-quickstart/
├── app/
│   ├── layout.tsx          # Root layout with ClerkProvider
│   ├── page.tsx            # Home page component
│   └── globals.css         # Global styles
├── proxy.ts                # Clerk middleware configuration
├── next.config.ts          # Next.js configuration
├── tsconfig.json           # TypeScript configuration
├── postcss.config.mjs      # PostCSS configuration
├── eslint.config.js        # ESLint configuration
├── package.json            # Dependencies
└── .env.example            # Environment variables template
```

--------------------------------

### Next.js Configuration Usage Example

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/types.md

Example of how to declare and export a Next.js configuration object using the NextConfig type.

```typescript
const nextConfig: NextConfig = {
  /* config options here */
};

export default nextConfig;
```

--------------------------------

### Environment Variables Example

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/file-structure.md

Template for environment variables, including Clerk publishable and secret keys. Copy this to .env.local and fill in actual values.

```bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
```

--------------------------------

### Next.js Metadata Usage Example

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/types.md

Example of defining metadata for a Next.js page, including title and description.

```typescript
export const metadata: Metadata = {
  title: 'Clerk Next.js Quickstart',
  description: 'Generated by create next app',
}
```

--------------------------------

### Complete Next.js Layout with Clerk Components

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

A full example of app/layout.tsx demonstrating the integration of ClerkProvider, SignInButton, SignUpButton, Show, and UserButton for a complete authentication UI.

```typescript
// app/layout.tsx
import type { Metadata } from 'next'
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  Show,
  UserButton,
} from '@clerk/nextjs'
import './globals.css'

export const metadata: Metadata = {
  title: 'Clerk Next.js Quickstart',
  description: 'Generated by create next app',
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClerkProvider>
          <header>
            <Show when="signed-out">
              <SignInButton />
              <SignUpButton />
            </Show>
            <Show when="signed-in">
              <UserButton />
            </Show>
          </header>
          {children}
        </ClerkProvider>
      </body>
    </html>
  )
}
```

--------------------------------

### Getting User Data in Client and Server Components

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Provides examples for fetching user data using `useUser` hook in client components and `currentUser` function in server components.

```typescript
// Client component
import { useUser } from '@clerk/nextjs';

const { user } = useUser();
// user.firstName, user.emailAddresses[0].emailAddress, etc.

// Server component
import { currentUser } from '@clerk/nextjs/server';

const user = await currentUser();
// Same user object
```

--------------------------------

### Complete Example: API Route and Client Form

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-hooks-and-helpers.md

Demonstrates combining server-side protection in an API route with client-side checks and authenticated requests using `useAuth()` in a form component.

```typescript
// app/api/posts/route.ts
import { auth } from '@clerk/nextjs/server';

export async function POST(req: Request) {
  const { userId, protect } = await auth();
  
  // Require authentication
  protect();
  
  const body = await req.json();
  
  // Create post for authenticated user
  const post = await db.posts.create({
    data: {
      title: body.title,
      content: body.content,
      authorId: userId,
    }
  });
  
  return Response.json(post);
}

// app/components/post-form.tsx
'use client';

import { useAuth } from '@clerk/nextjs';
import { useState } from 'react';

export function PostForm() {
  const { isSignedIn } = useAuth();
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');
  
  if (!isSignedIn) {
    return <p>Sign in to create posts</p>;
  }
  
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    
    const response = await fetch('/api/posts', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ title, content })
    });
    
    if (response.ok) {
      setTitle('');
      setContent('');
      // Refresh posts list
    }
  }
  
  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Title"
      />
      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        placeholder="Content"
      />
      <button type="submit">Create Post</button>
    </form>
  );
}
```

--------------------------------

### Clerk Next.js App Router Architecture Overview

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

Visual representation of the Clerk Next.js Quickstart architecture, illustrating the flow from the user browser to the Next.js server and back.

```text
┌─────────────────────────────────────────────────────────────┐
│                    User Browser                             │
│  - Clicks sign-in/sign-up button                            │
│  - Opens Clerk authentication modal                         │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP Request
                       ▼
┌──────────────────────────────────────────────────────────────┐
│            Next.js Server (Node.js Process)                 │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Middleware (proxy.ts)                                 │ │
│  │  - clerkMiddleware() initializes auth context          │ │
│  │  - Matcher: includes dynamic pages, /api, /trpc       │ │
│  │  - Excludes: _next internals, static files             │ │
│  └────────────────────────────────────────────────────────┘ │
│                       │                                      │
│                       ▼                                      │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Route Handler (Page or API)                           │ │
│  │  - app/layout.tsx (root)                               │ │
│  │  - app/page.tsx (home)                                 │ │
│  │  - Available: Clerk context via auth(), hooks          │ │
│  └────────────────────────────────────────────────────────┘ │
│                       │                                      │
│                       ▼                                      │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Component Tree                                        │ │
│  │  <html>                                                │ │
│  │    <ClerkProvider>  ← Wrap entire app                  │ │
│  │      <header>                                          │ │
│  │        <Show when="signed-out">
│  │          <SignInButton/>  <SignUpButton/>              │ │
│  │        </Show>                                         │ │
│  │        <Show when="signed-in">                         │ │
│  │          <UserButton/>                                 │ │
│  │        </Show>                                         │ │
│  │      </header>                                         │ │
│  │      {children}  ← Page content                        │ │
│  │    </ClerkProvider>                                    │ │
│  │  </html>                                               │ │
│  └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
                       │ HTTP Response
                       ▼
┌──────────────────────────────────────────────────────────────┐
│                  Browser Renders Page                        │ │
│  - Clerk modal shown or hidden based on auth state           │
│  - Sign-in/sign-up buttons visible if signed-out             │
│  - User menu visible if signed-in                            │
└──────────────────────────────────────────────────────────────┘
```

--------------------------------

### Next.js Build and Runtime Configuration Options

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/file-structure.md

Example of common configuration options that can be set in the next.config.ts file for image optimization, environment variables, redirects, headers, Webpack customization, and React StrictMode.

```typescript
{
  images: { ... },       // Image optimization
  env: { ... },          // Environment variables
  redirects: async => [] // URL redirects
  headers: async => [],  // Custom HTTP headers
  webpack: (config) => { }, // Webpack customization
  reactStrictMode: true  // React StrictMode
}
```

--------------------------------

### Root Layout with ClerkProvider and Auth Components

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Set up the root layout for your Next.js application using ClerkProvider. This example demonstrates how to conditionally render SignInButton, SignUpButton, and UserButton based on the user's authentication status.

```typescript
import { ClerkProvider, SignInButton, SignUpButton, Show, UserButton } from '@clerk/nextjs'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ClerkProvider>
          <header>
            <Show when="signed-out">
              <SignInButton />
              <SignUpButton />
            </Show>
            <Show when="signed-in">
              <UserButton />
            </Show>
          </header>
          {children}
        </ClerkProvider>
      </body>
    </html>
  )
}
```

--------------------------------

### Force Install Dependencies with pnpm

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

If you encounter dependency conflicts, especially with React RC versions, use the --force flag with pnpm install to resolve them.

```bash
pnpm install --force
```

--------------------------------

### Customizing Sign-In/Sign-Up Buttons

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Example of customizing the appearance and behavior of Clerk's `SignInButton` and `SignUpButton` components within a Next.js layout.

```typescript
// app/layout.tsx
import { SignInButton, SignUpButton } from '@clerk/nextjs';

<header>
  <Show when="signed-out">
    <SignInButton>
      <button>Login</button>  {/* Custom button */}
    </SignInButton>
    <SignUpButton mode="modal">
      Create Account
    </SignUpButton>
  </Show>
</header>
```

--------------------------------

### Dockerfile for Clerk Next.js App

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

A Dockerfile to containerize the Clerk Next.js application. It installs pnpm, installs dependencies, builds the project, and exposes port 3000 for the production server.

```dockerfile
FROM node:20-alpine

WORKDIR /app

# Install pnpm
RUN npm install -g pnpm@10.33.4

# Copy files
COPY package.json pnpm-lock.yaml ./ 

# Install dependencies
RUN pnpm install --frozen-lockfile

# Copy source
COPY . .

# Build
RUN pnpm build

# Expose port
EXPOSE 3000

# Start production server
CMD ["pnpm", "start"]
```

--------------------------------

### Package.json Scripts for Build and Development

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/configuration.md

Common npm scripts for managing the Next.js application lifecycle. Includes commands for development, building, starting the production server, and linting.

```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint ."
  }
}
```

--------------------------------

### Deploy Clerk Next.js App to EC2 Instance

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Steps to deploy the Clerk Next.js application on an EC2 instance. This includes setting up Node.js, installing dependencies, configuring environment variables, building the app, and running it with PM2.

```bash
# SSH into instance
ssh -i key.pem ec2-user@your-instance.amazonaws.com

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
npm install -g pnpm

# Clone repository
git clone https://github.com/yourusername/repo.git
cd repo

# Set environment variables
cat > .env.local <<EOF
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxx
CLERK_SECRET_KEY=sk_live_xxx
EOF

# Install and build
pnpm install
pnpm build

# Start with PM2 (process manager)
npm install -g pm2
pm2 start "pnpm start" --name clerk-app
pm2 save
```

--------------------------------

### Package.json - Project Metadata, Dependencies, and Scripts

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/file-structure.md

The package.json file defines project metadata, private status, scripts for development, building, starting, and linting, as well as core dependencies like Clerk, Next.js, and React.

```json
{
  "name": "clerk-nextjs-app-quickstart",
  "version": "0.1.0",
  "private": true,
  
  "scripts": {
    "dev": "next dev",          // Development server
    "build": "next build",      // Production build
    "start": "next start",      // Production server
    "lint": "eslint ."          // Code quality check
  },
  
  "dependencies": {
    "@clerk/nextjs": "^7.2.2",  // Authentication
    "next": "^16.0.7",          // Framework
    "react": "^19.2.1",         // UI library
    "react-dom": "^19.2.1"      // DOM rendering
  },
  
  "devDependencies": {
    // Dev-only tools for TypeScript, Tailwind, ESLint, etc.
  },
  
  "packageManager": "pnpm@10.33.4+..." // Lock pnpm version
}
```

--------------------------------

### RootLayout Component Usage

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/types.md

Example of how the RootLayout component is used to wrap the application with ClerkProvider.

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

--------------------------------

### Core Clerk Next.js Imports

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/components.md

These are the primary UI integration points for Clerk authentication in a Next.js quickstart template. Ensure these imports are present to use Clerk components.

```typescript
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  Show,
  UserButton,
} from '@clerk/nextjs'
```

--------------------------------

### Prisma Schema Configuration

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Define your database schema using Prisma's schema definition language. This example configures a PostgreSQL database connection using an environment variable and defines a 'User' model.

```prisma
datasource db {
  provider = "postgresql"
  url      = env("POSTGRES_URL")
}

model User {
  id        String   @id @default(cuid())
  clerkId   String   @unique
  email     String   @unique
  firstName String?
  lastName  String?
  createdAt DateTime @default(now())
}
```

--------------------------------

### Create User in API Route with Prisma

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Example of an API route in Next.js that creates a new user in the database using Prisma. It retrieves the authenticated user's ID from Clerk and uses data from the request body.

```typescript
import { auth } from '@clerk/nextjs/server';
import { db } from '@/lib/db'; // Prisma client

export async function POST(req: Request) {
  const { userId } = await auth();
  
  const user = await db.user.create({
    data: {
      clerkId: userId,
      email: req.json().email,
    }
  });
  
  return Response.json(user);
}
```

--------------------------------

### Fetching User Data with Clerk and Database

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Retrieve user information from your database using the authenticated `userId` provided by Clerk's `auth()` function. This example demonstrates fetching a user by their Clerk ID.

```typescript
// app/api/users/route.ts
import { auth } from '@clerk/nextjs/server';

export async function GET() {
  const { userId } = await auth();
  
  // Connect to database
  const user = await db.users.findUnique({
    where: { clerkId: userId }
  });
  
  return Response.json(user);
}
```

--------------------------------

### Server Component Authentication Check

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/middleware.md

Example of how to access user authentication status within a Next.js server component using the `auth()` helper. Redirects or shows content based on whether a user is signed in.

```typescript
import { auth } from '@clerk/nextjs/server';

export default async function ProtectedPage() {
  const {userId} = await auth();
  
  if (!userId) {
    return <div>Not signed in</div>;
  }
  
  return <div>Welcome, user {userId}</div>;
}
```

--------------------------------

### Run the Development Server

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/README.md

Launch the local development server to test the Clerk Next.js application.

```bash
pnpm run dev
```

--------------------------------

### Set Up .env.local for Clerk Keys

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/configuration.md

Create a .env.local file in your project root to store your Clerk publishable and secret keys. These are essential for Clerk authentication to function correctly.

```bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
CLERK_SECRET_KEY=sk_test_your_secret_key_here
```

--------------------------------

### Environment Variables Template

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

The `.env.example` file provides a template for necessary environment variables, including Clerk publishable and secret keys.

```env
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

```

--------------------------------

### Development vs. Production Clerk Keys

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Use test keys for development and live keys for production. Ensure you retrieve your live keys from the Clerk Dashboard.

```bash
# Use test/sandbox keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
```

```bash
# Use live/production keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxx
CLERK_SECRET_KEY=sk_live_xxx
```

--------------------------------

### TypeScript Path Alias Usage

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/api-reference.md

Example of how to use a path alias defined in `tsconfig.json` for cleaner import paths in your code.

```typescript
// tsconfig.json
"paths": {
  "@/*": ["./*"]
}

// Usage in code
import Component from '@/app/component'  // Instead of ../../app/component
```

--------------------------------

### Build and Run Docker Container

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Build a Docker image for the Clerk Next.js application and run it as a container. Environment variables for Clerk keys must be passed during container runtime.

```bash
# Build image
docker build -t clerk-nextjs-app .

# Run container
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxx \
  -e CLERK_SECRET_KEY=sk_live_xxx \
  clerk-nextjs-app
```

--------------------------------

### Build Command

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Execute the build command to check your application's build size. The output will detail the size of different routes.

```bash
pnpm build

# Output shows:
# ○ /                           12.5 kB
# ○ /page                       9.2 kB
# ...
```

--------------------------------

### Get Authentication Token for External API Calls

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-hooks-and-helpers.md

Obtain an authentication token using the getToken() method from auth() to make authenticated requests to external APIs.

```typescript
const { getToken } = await auth();

const token = await getToken();
const response = await fetch('https://external-api.com/data', {
  headers: { Authorization: `Bearer ${token}` }
});
```

--------------------------------

### Get User ID for Database Queries

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-hooks-and-helpers.md

Retrieve the authenticated user's ID using the auth() helper to perform database operations specific to that user.

```typescript
const { userId } = await auth();

const userProfile = await db.users.findUnique({
  where: { clerkId: userId }
});
```

--------------------------------

### Get Authentication Token

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-hooks-and-helpers.md

Use the 'getToken' function from the useAuth hook to retrieve an authentication token. This token can be included in the 'Authorization' header for protected API requests.

```typescript
const { getToken } = useAuth();

const token = await getToken();
const response = await fetch('/api/protected', {
  headers: { Authorization: `Bearer ${token}` }
});
```

--------------------------------

### Basic SignUpButton Usage

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/components.md

Renders a button that initiates the Clerk sign-up flow. It supports default or custom content for the button.

```typescript
<SignUpButton />
```

```typescript
<SignUpButton>Create Account</SignUpButton>
```

--------------------------------

### Static Asset Serving Logic

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

Demonstrates how Next.js serves static assets directly without invoking middleware if the request path matches the exclusion patterns defined in `config.matcher`.

```text
Request for /image.png
    ↓
Check matcher config
    ↓
    Pattern: /((?!_next|[^?]*\.(?:...)).*)/
    ├─ File ends with .png
    ├─ Matches static extension exclusion
    └─ Skip middleware
    ↓
Next.js serves static file directly
(faster, no authentication overhead)

```

--------------------------------

### Set Clerk Environment Variables for Production

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Configure your production environment with Clerk's publishable and secret keys. Use LIVE keys for production deployments and TEST keys for preview or staging environments.

```bash
Variable: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
Value: pk_live_xxxxx                           # Your LIVE Clerk key
Environment: Production (and Preview if desired)

Variable: CLERK_SECRET_KEY
Value: sk_live_xxxxx                           # Your LIVE Clerk key
Environment: Production (and Preview if desired)
```

--------------------------------

### Root Layout with ClerkProvider and Conditional Rendering

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Demonstrates how to wrap the entire application with ClerkProvider in the root layout and conditionally render sign-in/sign-up buttons or the user button based on authentication status.

```typescript
<ClerkProvider>
  <header>
    <Show when="signed-out">
      <SignInButton />
      <SignUpButton />
    </Show>
    <Show when="signed-in">
      <UserButton />
    </Show>
  </header>
  {children}
</ClerkProvider>
```

--------------------------------

### Getting Auth Token for API Requests

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Illustrates how to obtain the authentication token using the `useAuth` hook in a client component and include it in the `Authorization` header for API requests.

```typescript
const { getToken } = useAuth();
const token = await getToken();

fetch('/api/endpoint', {
  headers: { Authorization: `Bearer ${token}` }
});

```

--------------------------------

### Get User ID for API Calls

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-hooks-and-helpers.md

Retrieve the 'userId' from the useAuth hook to make authenticated API requests. This allows you to personalize API endpoints or identify the user making the request.

```typescript
const { userId } = useAuth();

const response = await fetch(`/api/users/${userId}`);
```

--------------------------------

### Default SignUpButton

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Renders a button with the default 'Sign Up' text. Use this for a standard sign-up button.

```typescript
<SignUpButton />
// Renders a button with text "Sign Up"
```

--------------------------------

### Deploy to Vercel using CLI

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Command to deploy your Next.js application to Vercel using the Vercel CLI.

```bash
npm install -g vercel
vercel
```

--------------------------------

### Show Component Import

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Demonstrates how to import the Show component from the Clerk Next.js SDK.

```typescript
import { Show } from '@clerk/nextjs'
```

--------------------------------

### Middleware Initialization

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

The `clerkMiddleware` function from `@clerk/nextjs/server` is exported as the default middleware. This initializes the authentication context for all incoming requests that match the configured route matchers.

```typescript
import clerkMiddleware from "@clerk/nextjs/server"

export default clerkMiddleware()

```

--------------------------------

### useClerk()

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-hooks-and-helpers.md

The `useClerk` hook provides programmatic control over Clerk's authentication flows and modals. It exposes methods such as `signOut`, `openSignIn`, `openSignUp`, and `openUserProfile` to manage user sessions and UI interactions.

```APIDOC
## useClerk()

### Description
Provides programmatic control over Clerk modals and authentication operations.

### Type Signature
```typescript
function useClerk(): {
  signOut: () => Promise<void>
  openSignIn: () => Promise<void>
  openSignUp: () => Promise<void>
  openUserProfile: () => Promise<void>
  // ... additional methods
}
```

### Return Value
- **`signOut()`** (Promise<void>) - Sign out current user
- **`openSignIn()`** (Promise<void>) - Open sign-in modal
- **`openSignUp()`** (Promise<void>) - Open sign-up modal
- **`openUserProfile()`** (Promise<void>) - Open user profile settings

### Purpose
Programmatically control Clerk modals and operations.

### Usage Example
```typescript
'use client';

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

export function CustomAuthButtons() {
  const { signOut, openSignIn, openSignUp } = useClerk();
  
  return (
    <div>
      <button onClick={openSignIn}>
        Sign In
      </button>
      <button onClick={openSignUp}>
        Sign Up
      </button>
      <button onClick={signOut}>
        Sign Out
      </button>
    </div>
  );
}
```
```

--------------------------------

### Run Linter with pnpm

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Execute this command to check your code for style and potential errors using the project's configured linter. It helps maintain code quality.

```bash
pnpm lint
```

--------------------------------

### File Organization Structure

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Illustrates the typical file and directory structure for a Clerk-integrated Next.js application.

```tree
app/
  layout.tsx        ← Root layout, wrap with ClerkProvider
  page.tsx          ← Home page
  globals.css       ← Global styles
proxy.ts            ← Middleware, clerkMiddleware()
next.config.ts      ← Next.js config	sconfig.json       ← TypeScript config
package.json        ← Dependencies
.env.local          ← API keys (SECRET, don't commit)
```

--------------------------------

### ClerkProvider Usage in layout.tsx

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Wrap your application's root layout with ClerkProvider to enable Clerk authentication context for all child components. This setup ensures that components like SignInButton, UserButton, and hooks like useAuth are available.

```typescript
// app/layout.tsx
<html>
  <body>
    <ClerkProvider>
      <header>
        {/* All content here has access to Clerk context */}
      </header>
      {children}  {/* Page components */}
    </ClerkProvider>
  </body>
</html>
```

--------------------------------

### Verify .env.local Contents

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/setup-guide.md

Commands to verify the existence and contents of the `.env.local` file, which is crucial for loading Clerk API keys in a Next.js development environment.

```bash
# Verify .env.local exists
ls -la .env.local

# Check contents (mask secret key)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
```

--------------------------------

### Home Page Imports

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/file-structure.md

Imports the Image component from Next.js for optimized image rendering on the home page.

```typescript
import Image from "next/image"
```

--------------------------------

### Middleware Execution Logic

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

Illustrates how Next.js middleware is executed. It checks the request path against `config.matcher` and conditionally executes `clerkMiddleware()` if the path is not excluded (e.g., `_next` routes or static files).

```text
Request arrives
    ↓
Next.js checks config.matcher against path
    ↓
  ├─ Path matches "/" → YES
  │  ├─ Not in _next → true
  │  ├─ Not a static file → true
  │  └─ execute clerkMiddleware()
  │
  ├─ Path matches "/api/users" → YES
  │  ├─ Matches /(api|trpc)(.*) → true
  │  └─ execute clerkMiddleware()
  │
  └─ Path matches "/_next/static/..." → NO
     ├─ Matches _next exclusion → false
     └─ Skip middleware, serve static file

clerkMiddleware() execution:
    ↓
  1. Read auth cookie or header
  2. If valid session → attach to context
  3. If no session → context.userId = null
  4. Continue to route handler
    ↓
Route handler accesses context:
    ↓
  Server: const { userId } = await auth()
  Client: const { isSignedIn } = useAuth()
    ↓
Component renders based on auth state

```

--------------------------------

### Next.js Build Commands

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Common pnpm commands for managing a Next.js development server, building for production, running the production build, and linting the codebase.

```bash
pnpm dev      # Dev server (hot reload)
pnpm build    # Production build
pnpm start    # Run production build
pnpm lint     # Run ESLint
```

--------------------------------

### Basic Next.js File Structure

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Illustrates the standard file structure for a Next.js application, including the root layout, page components, API routes, and nested layouts.

```plaintext
app/
  layout.tsx          # Root layout (always rendered)
  page.tsx            # / route
  api/
    users/
      route.ts        # GET /api/users
  dashboard/
    page.tsx          # /dashboard route
    layout.tsx        # Layout for /dashboard/* (nested)

```

--------------------------------

### ClerkProvider and Conditional Rendering in Layout

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

Shows how to wrap the application with ClerkProvider and use the Show component for conditional UI rendering based on authentication status.

```javascript
Root layout renders:
  <ClerkProvider>
    <header>
      <Show when="signed-out">
        Render sign-in/sign-up buttons
      </Show>
      <Show when="signed-in">
        Render user menu
      </Show>
    </header>
    {children}
  </ClerkProvider>
↓
Show component checks auth state from ClerkProvider context
↓
Renders appropriate buttons or menu based on isSignedIn
```

--------------------------------

### Environment Variables Template

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/api-reference.md

This file serves as a template for environment variables. Copy it to .env.local and fill in your Clerk API keys.

```bash
# Visit https://dashboard.clerk.com/~/api-keys to find your API Keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

```

--------------------------------

### SignUpButton

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Renders a button that initiates the Clerk sign-up flow. It supports custom text, HTML elements, modal mode, and redirection after sign-up. It automatically handles authentication state and form submissions.

```APIDOC
## SignUpButton

### Description

Renders a clickable button that initiates the Clerk sign-up flow. Similar to `SignInButton` but for account creation. It supports custom text, HTML elements, modal mode, and redirection after sign-up.

### Props

```typescript
interface SignUpButtonProps {
  children?: React.ReactNode
  mode?: 'redirect' | 'modal'
  fallbackRedirectUrl?: string
  [key: string]: any
}
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | "Sign Up" | Custom button text or element. If not provided, renders default "Sign Up" button. |
| `mode` | `'redirect' | 'modal'` | 'redirect' | `'redirect'` navigates to sign-up page. `'modal'` opens sign-up modal. |
| `fallbackRedirectUrl` | string | '/' | URL to redirect to after successful account creation. Default is home page. |

### Behavior

- Displays as a clickable button (customizable appearance).
- Clicking opens the sign-up flow (modal or redirect).
- Automatically handles form display, input validation, email verification, account creation, session initialization, and redirection.
- Only visible when user is signed out (manage visibility with `Show` component).

### Usage Examples

**Default Style:**

```typescript
<SignUpButton />
// Renders a button with text "Sign Up"
```

**Custom Text:**

```typescript
<SignUpButton>Create Account</SignUpButton>
```

**Custom HTML:**

```typescript
<SignUpButton>
  <a href="#" className="button button-primary">Register</a>
</SignUpButton>
```

**Modal Mode:**

```typescript
<SignUpButton mode="modal">
  Join Us
</SignUpButton>
```

**Redirect to Onboarding:**

```typescript
<SignUpButton fallbackRedirectUrl="/onboarding">
  Get Started
</SignUpButton>
```

**In Template Context:**

```typescript
// app/layout.tsx
<Show when="signed-out">
  <SignInButton />
  <SignUpButton />
</Show>
```
```

--------------------------------

### Common Next.js Configuration Options

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/types.md

Provides a reference for frequently used configuration options within the NextConfig type.

```typescript
type NextConfig = {
  basePath?: string                    // URL path prefix
  compress?: boolean                   // Enable gzip compression
  redirects?: () => Promise<Redirect[]> // URL redirects
  rewrites?: () => Promise<Rewrite>   // URL rewrites
  headers?: () => Promise<Header[]>   // Custom HTTP headers
  images?: ImageConfig                 // Image optimization settings
  webpack?: (config, context) => object // Webpack config override
  reactStrictMode?: boolean            // React StrictMode wrapper
  // ... many more options
}
```

--------------------------------

### Home Component with Clerk Authentication (Server-side)

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/api-reference.md

Demonstrates how to access Clerk authentication status on the server-side within the Home component. Requires importing `auth` from `@clerk/nextjs/server`.

```typescript
import { auth } from '@clerk/nextjs/server';

export default async function Home() {
  const {userId} = await auth();
  
  return (
    <div>
      {userId ? <p>Welcome back!</p> : <p>Sign in to get started</p>}
    </div>
  );
}
```

--------------------------------

### Import SignInButton

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Import the SignInButton component from the '@clerk/nextjs' package. This component renders a button that initiates the sign-in process.

```typescript
import { SignInButton } from '@clerk/nextjs'
```

--------------------------------

### clerkMiddleware()

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/api-reference.md

Initializes Clerk authentication context for the current request. The returned middleware function is automatically called by Next.js for all routes matching the `config.matcher` pattern.

```APIDOC
## clerkMiddleware()

### Description
Initializes Clerk authentication context for the current request. The returned middleware function is automatically called by Next.js for all routes matching the `config.matcher` pattern.

### Method
Not applicable (Next.js Middleware)

### Endpoint
Not applicable (Next.js Middleware)

### Parameters
None

### Returns
Middleware function that processes requests and returns responses

### Usage
```typescript
// proxy.ts
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

export const config = {
  matcher: [
    // Routes where clerkMiddleware runs
    '/((?!_next|[^?]*\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
}
```

### Error Handling
- Does not throw on invalid tokens; treats as signed-out
- Allows unauthenticated requests to proceed
- Use `auth()` helper in route handlers to enforce authentication if needed
```

--------------------------------

### Root Layout with ClerkProvider

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

The root layout wraps the entire application with `ClerkProvider`. It conditionally renders sign-in buttons or a user menu based on the authentication state, making authentication context available to all child components.

```typescript
import { ClerkProvider, SignInButton, Show, SignUpButton, UserButton } from "@clerk/nextjs"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>
          <header>
            <Show when="signed-out">
              <SignInButton />
              <SignUpButton />
            </Show>
            <Show when="signed-in">
              <UserButton />
            </Show>
          </header>
          {children}
        </body>
      </html>
    </ClerkProvider>
  )
}

```

--------------------------------

### Serving Static Assets in Next.js

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/file-structure.md

Demonstrates how to reference static assets like images within a Next.js application. These assets are served directly from the public directory.

```typescript
<img src="/next.svg" alt="Next.js" />
```

--------------------------------

### Basic SignInButton Usage

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/components.md

Renders a button that initiates the Clerk sign-in flow. It can be used with default text or custom content.

```typescript
<SignInButton />
```

```typescript
<SignInButton>Login</SignInButton>
```

```typescript
<SignInButton>
  <a href="#" className="custom-button">Sign In Here</a>
</SignInButton>
```

--------------------------------

### Protecting a Page with Server Component and Redirect

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/quick-reference.md

Shows how to protect a server component page by checking for `userId` and redirecting to the home page if the user is not signed in.

```typescript
import { auth } from '@clerk/nextjs/server';
import { redirect } from 'next/navigation';

export default async function PrivatePage() {
  const { userId } = await auth();
  
  if (!userId) {
    redirect('/');  // Redirect to home if not signed in
  }
  
  return <div>Private content</div>;
}
```

--------------------------------

### Modal Mode SignUpButton

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Configures the SignUpButton to open the sign-up flow in a modal window instead of navigating to a separate page. Use 'mode="modal"' to enable.

```typescript
<SignUpButton mode="modal">
  Join Us
</SignUpButton>
```

--------------------------------

### Optimizing Build Size with Dynamic Imports

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/deployment.md

Use dynamic imports for large components to reduce initial bundle size and improve page load performance. The `loading` option can display a fallback while the component loads.

```typescript
// Use dynamic imports for large components
import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(
  () => import('./heavy-component'),
  { loading: () => <div>Loading...</div> }
);
```

--------------------------------

### Basic UserButton Usage

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/components.md

Renders a button that displays the signed-in user's information and opens a menu with account management options. This component is only visible when a user is signed in.

```typescript
<UserButton />
```

--------------------------------

### Home Component with Clerk Authentication (Client-side)

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/api-reference.md

Shows how to use the `useAuth` hook in a client component to access Clerk authentication status. Requires the `'use client'` directive.

```typescript
'use client';

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

export function UserGreeting() {
  const {isSignedIn} = useAuth();
  return isSignedIn ? <p>Welcome!</p> : <p>Sign in</p>;
}
```

--------------------------------

### Package JSON Dependencies

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/architecture.md

The `package.json` file lists project dependencies, including the Clerk SDK for Next.js, the Next.js framework, and React libraries.

```json
{
  "dependencies": {
    "@clerk/nextjs": "^5.0.0",
    "next": "^14.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

```

--------------------------------

### Multiple Conditions in Header

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Demonstrates how to use the Show component to conditionally render different header content based on the user's authentication status.

```typescript
<header>
  <Show when="signed-out">
    <h1>Welcome to our site</h1>
    <SignInButton />
    <SignUpButton />
  </Show>
  
  <Show when="signed-in">
    <h1>Welcome back!</h1>
    <UserButton />
  </Show>
</header>
```

--------------------------------

### Root Layout Imports

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/file-structure.md

Imports necessary components and types for the root layout, including ClerkProvider and UI components.

```typescript
import type { Metadata } from 'next'
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  Show,
  UserButton,
} from '@clerk/nextjs'
import './globals.css'
```

--------------------------------

### Show Component in Template Context (Header)

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Illustrates a common pattern for managing header content in a Next.js application using the Show component for conditional rendering based on authentication state.

```typescript
// app/layout.tsx
<header>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <UserButton />
  </Show>
</header>
```

--------------------------------

### Customizing SignInButton Styling

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/clerk-components-reference.md

Shows how to apply custom CSS classes or compose custom content for the SignInButton.

```typescript
// Default button styling provided
<SignInButton />

// Custom button styling
<SignInButton>
  <button className="custom-button-class">
    Log In
  </button>
</SignInButton>

// Custom component composition
<SignInButton>
  <span className="icon">→</span> Sign In
</SignInButton>
```

--------------------------------

### Basic Next.js Configuration

Source: https://github.com/clerk/clerk-nextjs-app-quickstart/blob/main/_autodocs/configuration.md

An empty next.config.ts file. Extend this file as needed for additional Next.js features and configurations.

```typescript
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
};

export default nextConfig;
```