Clerk Authentication Setup

Clerk is a modern authentication platform that provides beautiful, customizable UI components and a developer-friendly experience. This guide walks you through integrating Clerk authentication with your Zudoku documentation site.

Prerequisites

If you don't have a Clerk account, you can sign up for a free Clerk account that provides 10,000 monthly active users.

Setup Steps

1. Create a Clerk Application

   In the Clerk Dashboard:

   • Click Create Application
   • Enter your application name
   • Select your preferred authentication methods (email, social providers, etc.)
   • Click Create Application

2. Create a Clerk JWT Template You need to create a JWT Template so your JWTs include name, email and email_verified information.

• Navigate to JWT templates in the Clerk Dashboard
• Create a new template by clicking Add new template
• Pick a name for the template
• Add the following claims

  Code
   
  {
    "name": "{{user.full_name}}",
    "email": "{{user.primary_email_address}}",
    "email_verified": "{{user.email_verified}}"
  }

• Save

3. Configure Zudoku

   Get your publishable key from the Clerk dashboard:

   • Navigate to API Keys in your Clerk dashboard
   • Copy the Publishable key

   Use the JWT template name defined in the previous section

   Add the Clerk configuration to your Zudoku configuration file:

   Code
    
   // zudoku.config.ts
   export default {
     // ... other configuration
     authentication: {
       type: "clerk",
       clerkPubKey: "<your-clerk-publishable-key>",
       jwtTemplateName: "<your-clerk-jwt-template-name>",
     },
     // ... other configuration
   };

4. Configure Redirect URLs (Optional)

   If you need custom redirect behavior, configure the allowed redirect URLs in Clerk:

   • Go to Paths in your Clerk dashboard
   • Add your production, preview, and local development URLs to the allowed redirect URLs
   • Common patterns:
     • Production: https://your-site.com/oauth/callback
     • Preview (wildcard): https://*.your-domain.com/oauth/callback
     • Local Development: http://localhost:3000/oauth/callback

5. Install Clerk Dependencies

   Add @clerk/clerk-js to your project dependencies:

   Code
    
   npm install @clerk/clerk-js

Troubleshooting

Common Issues

1. Invalid Publishable Key: Ensure you're using the publishable key (starts with pk_) and not the secret key.

2. Authentication Not Working: Verify that your Clerk application is active and not in development mode when deploying to production.

3. Redirect Issues: Check that your domain is added to the allowed redirect URLs in Clerk if using custom redirects.

4. ReferenceError: can't access lexical declaration 'xxx' before initialization: Make sure you have installed Clerk to your project.

Next Steps

• Explore Clerk's documentation for advanced features
• Learn about protecting routes in your documentation
• Configure user roles and permissions in Clerk