Set up a preview environment with Clerk

Popular hosting providers such as Cloudflare, Vercel, and more, offer preview deployments, which enable you to view changes to your site in a live environment before merging and deploying them to production.

There are two approaches to using Clerk in a preview environment:

• If you want to share production data with your preview environment, use Vercel's Preview Deployment Suffix.
• If you do not want to, or are not able to, expose production Clerk data to your preview environment, use your development API keys.

Vercel Preview Deployment Suffix

If you would like your preview environment to share a userbase with your production environment, you can use Vercel's Preview Deployment Suffix feature.⁠ Preview Deployment Suffixes allow you to customize the URL of a preview deployment by replacing the default vercel.app suffix with a custom domain of your choice.

To use Clerk with Vercel's Preview Deployment Suffix, you must have a Pro or Enterprise Vercel account.

The following steps will teach you how to configure your Vercel Preview Deployment Suffix with Clerk:

1. Acquire a separate domain - This domain will be used for your preview environment, and cannot be a subdomain of the domain used in your production environment. For example, if your production domain is my-site.com, you could use my-site-previews.com but you cannot use previews.my-site.com.
2. Follow the Deploy to Vercel guide - See the Preview URL section of the Deploy to Vercel guide to configure your app.
3. Contact Clerk support⁠ to provision a preview-specific Clerk app for free - If you are on a Pro, Enterprise, or Startup plan, Clerk will provision a dedicated preview-specific Clerk application with all the same features as your main application for free.
4. Use production instance API keys - Once Clerk support has provisioned your free preview-specific Clerk app, you should use its production instance API keys with your previews, as this offers better security and fewer limitations. See the production instance documentation to learn more.

Limitations

• This approach requires a Vercel Pro or Enterprise account.
• This approach locks you into using Vercel for preview environments.

Use your development API keys

If you would like your preview environment to have a different userbase from your production environment, you can set up your preview environment to use your development instance API keys.

To retrieve your development instance API keys:

1. Navigate to the Clerk Dashboard⁠.
2. Ensure that Development is selected at the top.
3. In the navigation sidebar, select API Keys.
4. Copy your keys.

Once you have your development instance API keys, you can add them to your environment variables.

The following are environment variable guides from some popular providers:

• Vercel⁠
• Netlify⁠
• Cloudflare⁠

Limitations of using development keys

The limitations of using development instance API keys in preview environments are:

• Added possibility of Clerk cookie errors. Remember to clear your cookies if you are encountering infinite redirects or authentication issues.
• Changes to user data will not be automatically mirrored in your main application for your production environment.
• There is a maximum user limit.
• Features enabled in your development instance will not be available in your production environment without upgrading your Clerk plan.
• Development instance API keys offer less security overall compared to production instance keys.

See the development instance documentation to learn more.

Staging environments

You can also use Clerk with staging environments.