Setting Up Clerk Authentication

Overview

This guide shows you how to enable Clerk authentication in your help center project. The project is pre-configured with authentication support - you just need to add your Clerk keys and choose your protection settings.

Quick Setup

Step 1: Get Your Clerk Keys

Create a free account at clerk.com
Create a new application in your Clerk dashboard
Go to API Keys and copy these two values:
- Publishable Key (starts with pk_)
- Secret Key (starts with sk_)

Step 2: Configure Environment Variables

Copy .env.example to .env.local and add your Clerk keys:

# Clerk Authentication - Only these two keys are needed
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
CLERK_SECRET_KEY=sk_test_your_key_here

Step 3: Choose Your Protection Level

In your .env.local, configure what you want to protect:

# Enable authentication system
NEXT_PUBLIC_AUTH_ENABLED=true

# Choose what to protect (true/false)
AUTH_PROTECT_CONTENT=false    # Protect all content (articles, categories)
AUTH_PROTECT_EDITOR=true      # Protect the /editor page (recommended)

Step 4: Switch to Authentication Middleware

Your project has two middleware files:

middleware.ts - Current: middleware (with auth)
basicMiddleware.ts - NoAuth: No authentication

To enable authentication:

# Backup the current middleware if you dont need auth
mv middleware.ts middleware-backup.ts

# Rename the basic middleare file
mv basicMiddleware.ts middleware.ts

# The authentication middleware is already in place
# Just restart your development server
npm run dev

Configuration Options

Protection Settings

Setting	Description	Recommended
`AUTH_PROTECT_CONTENT=false`	Anyone can view articles	✅ Public help center
`AUTH_PROTECT_CONTENT=true`	Login required to view content	❌ Private knowledge base
`AUTH_PROTECT_EDITOR=true`	Login required for /editor	✅ Always recommended
`AUTH_PROTECT_EDITOR=false`	Editor is publicly accessible	❌ Not recommended if you want to push to github automatically

Common Configurations

Public Help Center (Default):

NEXT_PUBLIC_AUTH_ENABLED=true
AUTH_PROTECT_CONTENT=false     # Anyone can read
AUTH_PROTECT_EDITOR=true       # Only signed-in users can edit

Private Knowledge Base:

NEXT_PUBLIC_AUTH_ENABLED=true
AUTH_PROTECT_CONTENT=true      # Login required to read
AUTH_PROTECT_EDITOR=true       # Login required to edit

No Authentication:

NEXT_PUBLIC_AUTH_ENABLED=false
# Other auth settings are ignored

Testing Your Setup

1. Start Development Server

npm run dev

2. Test Editor Protection

Visit /editor - you should be redirected to sign-in
Sign up/in with your email
After signing in, you should access the editor

3. Test Content Protection

If AUTH_PROTECT_CONTENT=true, visiting / should require login
If AUTH_PROTECT_CONTENT=false, content should be publicly accessible

How It Works

Project Structure

middleware.ts              # Active middleware (with Clerk)
basicMiddleware.ts        # Backup (no authentication)
lib/config.ts            # Reads environment variables

Authentication Flow

User visits protected route (e.g., /editor)
Middleware checks siteConfig.auth.enabled
If enabled, Clerk handles authentication
If disabled, request passes through

Environment Variable Flow

.env.local → lib/config.ts → middleware.ts → Route Protection

Troubleshooting

❗ "Clerk is not defined" error

Problem: Authentication middleware is active but Clerk keys are missing

Solution:

# Add both keys to .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

Problem: Editor protection is disabled

Solution:

# Enable editor protection
AUTH_PROTECT_EDITOR=true

❗ Can't access content after enabling auth

Problem: Content protection is enabled

Solution:

# Make content public (recommended for help centers)
AUTH_PROTECT_CONTENT=false

❗ Build errors with Clerk imports

Problem: This shouldn't happen with the middleware setup, but if it does:

Solution: Switch back to basic middleware temporarily

mv middleware.ts clerkMiddleware.ts
mv basicMiddleware.ts middleware.ts

Customization

The project uses Clerk's default sign-in UI. To customize:

Visit your Clerk dashboard → Customization
Adjust colors, logos, and branding
Changes apply automatically to your app

In your Clerk dashboard:

Go to User & Authentication → Social Connections
Enable providers (Google, GitHub, etc.)
No code changes needed

Production Deployment

Environment Variables

Add these to your hosting platform:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_your_production_key
CLERK_SECRET_KEY=sk_live_your_production_key
NEXT_PUBLIC_AUTH_ENABLED=true
AUTH_PROTECT_EDITOR=true
AUTH_PROTECT_CONTENT=false

Clerk Dashboard

Add your production domain to allowed domains
Use production keys (not test keys)
Configure any additional settings needed

Security Notes

✅ Only two Clerk keys needed - keep it simple
✅ Editor protection recommended - prevents unauthorized edits
✅ Content protection optional - depends on your use case
✅ Environment variables secure - never commit .env.local

Quick Start: Just add your two Clerk keys to .env.local, set NEXT_PUBLIC_AUTH_ENABLED=true and AUTH_PROTECT_EDITOR=true, then restart your server. Your editor will be protected while keeping your content publicly accessible.

✅ Email (recommended)
✅ Google (optional)
✅ GitHub (optional)

Click "Create Application"

Step 2: Configure Environment Variables

2.1 Get Your Clerk Keys

In your Clerk dashboard:

Navigate to "API Keys" in the sidebar
Copy your Publishable Key
Copy your Secret Key

2.2 Update Your .env.local File

Add the following to your .env.local file:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
CLERK_SECRET_KEY=sk_test_your_secret_key_here

# Editor Protection
AUTH_PROTECT_EDITOR=true

2.3 Environment Variable Explanation

Variable	Description	Required
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Public key for client-side auth	✅ Yes
`CLERK_SECRET_KEY`	Secret key for server-side auth	✅ Yes
`AUTH_PROTECT_EDITOR`	Enable editor protection	✅ Recommended

Step 3: Configure Allowed Domains (Optional)

3.1 For Production Deployment

In your Clerk dashboard, go to "Domains"
Add your production domain (e.g., https://yourdomain.com)
Add any staging domains if needed

3.2 For Development

Clerk automatically allows localhost for development, so no additional configuration is needed.

4.1 Customize Appearance

In your Clerk dashboard:

Go to "Customization" → "Appearance"
Choose your theme (Light/Dark)
Customize colors to match your brand
Upload your logo (optional)

Navigate to "User & Authentication" → "Email, Phone, Username"
Configure your preferred authentication methods:
- Email address: Required for most setups
- Username: Optional for simpler usernames
- Phone number: Optional for SMS verification

Go to "User & Authentication" → "Social Connections"
Enable desired providers:
- Google: Popular choice for help centers
- GitHub: Useful if your audience includes developers
- Microsoft: Good for enterprise users

Step 5: Test Your Setup

5.1 Start Your Development Server

npm run dev

5.2 Test Authentication

Navigate to /sign-in in your browser
Try signing up with a test account
Verify you can sign in and out
Test accessing the /editor page (should require authentication)

5.3 Verify Editor Protection

Try accessing /editor without signing in
You should be redirected to the sign-in page
After signing in, you should have access to the editor

Step 6: User Management

6.1 Managing Users

In your Clerk dashboard:

Go to "Users" to see all registered users
You can manually add users, ban users, or delete accounts
View user sessions and activity

Troubleshooting

Common Issues

❗ "Clerk keys not found"

Solution:

Verify your .env.local file has the correct keys
Ensure no extra spaces or quotes around the keys
Restart your development server after adding keys

❗ "Invalid domain" error

Solution:

Check that your domain is added in Clerk dashboard
Ensure the domain matches exactly (including https://)
For development, make sure you're using localhost:3000

❗ Editor still accessible without auth

Solution:

Confirm AUTH_PROTECT_EDITOR=true in your .env.local
Restart your development server
Clear your browser cache

Getting Help

If you encounter issues:

Clerk Documentation: docs.clerk.com
Clerk Discord: Join their community for support
GitHub Issues: Check the help center repository for known issues

Security Best Practices

🔒 Environment Variables

Never commit .env.local to version control
Use different keys for development and production
Rotate keys periodically

👤 User Management

Regularly review registered users
Remove inactive or suspicious accounts
Monitor sign-in attempts

🛡️ Access Control

Keep editor protection enabled
Consider additional role-based access if needed
Monitor editor usage through logs

Production Deployment

Environment Variables

When deploying to production:

Vercel: Add environment variables in your Vercel dashboard
Netlify: Configure variables in site settings
Other Platforms: Follow your platform's environment variable setup

Domain Configuration

Update Clerk dashboard with your production domain
Verify SSL certificate is properly configured
Test authentication on your live site

With Clerk authentication properly configured, your help center is now secure and ready for collaborative content creation. Users can safely access the editor while your content remains protected.

How can we help? 👋