Clerk 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 Dev Portal 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 Dev Portal 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 after sign-in or sign-up, you can configure this in your Dev Portal config:

   Code
   authentication: {
     type: "clerk",
     clerkPubKey: "<your-clerk-publishable-key>",
     jwtTemplateName: "<your-clerk-jwt-template-name>",
     redirectToAfterSignIn: "/docs",
     redirectToAfterSignUp: "/getting-started",
     redirectToAfterSignOut: "/",
   },

   You should also ensure your site's domain is added as an allowed origin in the Clerk dashboard.

5. Customizing Sign-up (Optional)

   To send Register to a different page, or hide it entirely:

   Code
   authentication: {
     type: "clerk",
     clerkPubKey: "<your-clerk-publishable-key>",
   
     // Absolute URL → external redirect, relative path → in-app navigate
     signUp: { url: "/register" },
   
     // Hide Register UI. Visual only — configure Clerk to actually block sign-ups.
     disableSignUp: true,
   },

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: This can happen if the Clerk CDN script fails to load. Check your network connectivity and ensure your publishable key is valid.

Next Steps

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