Zudoku
Supported Providers

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 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 
    JSONCode
    {
  "name": "{{user.full_name}}",
  "email": "{{user.primary_email_address}}",
  "email_verified": "{{user.email_verified}}"
}
  • Save

  1. 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:

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

  2. Configure Redirect URLs (Optional)

    If you need custom redirect behavior after sign-in or sign-up, you can configure this in your Zudoku config:

    TypeScriptCode
    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.

  3. Customizing Sign-up (Optional)

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

    TypeScriptCode
    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

Last modified on
Auth0Azure AD