Skip to content

Add guide for using production keys in local development#2959

Merged
manovotny merged 6 commits intomainfrom
manovotny/docs-11131-create-guide-on-using-production-keys-in-development
Jan 16, 2026
Merged

Add guide for using production keys in local development#2959
manovotny merged 6 commits intomainfrom
manovotny/docs-11131-create-guide-on-using-production-keys-in-development

Conversation

@manovotny
Copy link
Contributor

@manovotny manovotny commented Jan 13, 2026

🔎 Previews:

What does this solve?

Addresses DOCS-11131 by providing developers with a clear, step-by-step guide for debugging production-specific issues locally using production Clerk keys.

What changed?

  • Added new troubleshooting guide explaining how to map a subdomain to localhost
  • Included platform-specific instructions (macOS, Windows, Linux) for editing hosts files with user-friendly approaches
  • Documented Next.js configuration (allowedDevOrigins) required for production keys on non-standard ports
  • Provided HTTPS setup instructions with both --experimental-https and mkcert options
  • Added removal commands for cleanup after debugging
  • Documented key limitations (OAuth, webhooks, session behavior differences)

Testing

I've tested this locally myself using https://manovotny.xyz on a Mac.

Disclaimer: I did not test the Windows and Linux steps thoroughly as I don't have access to either OS. If someone has one of those machines and would like to test (or pair on testing), I'd appreciate it.

@manovotny manovotny requested a review from a team as a code owner January 13, 2026 16:52
@vercel
Copy link

vercel bot commented Jan 13, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Review Updated (UTC)
clerk-docs Ready Ready Preview Jan 15, 2026 11:14pm

Review with Vercel Agent

manovotny and others added 3 commits January 15, 2026 16:59
Adds a troubleshooting guide explaining how to debug production-specific
issues locally by mapping a subdomain to localhost. Covers hosts file
configuration, environment variables, HTTPS setup, and Next.js-specific
configuration.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updates the guide with simpler command-line approaches for macOS and
Linux, step-by-step GUI instructions for Windows, and corresponding
removal commands for cleaning up after debugging.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@manovotny manovotny force-pushed the manovotny/docs-11131-create-guide-on-using-production-keys-in-development branch from da2cae5 to 206f693 Compare January 15, 2026 22:59
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Copy link
Contributor

@SarahSoutoul SarahSoutoul left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really good! Love this new guide.

@manovotny manovotny merged commit 9e3b4f4 into main Jan 16, 2026
8 checks passed
@manovotny manovotny deleted the manovotny/docs-11131-create-guide-on-using-production-keys-in-development branch January 16, 2026 16:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants