Set up a preview environment with Clerk

Some popular hosting providers like Vercel and Netlify 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 high-level approaches to using Clerk in a preview environment:

1. Sharing production settings and user data
2. Using independent settings and user data

Sharing production settings and user data

To share production settings and user data with your preview environment, your preview environment must be hosted on the same root domain (but a separate subdomain) as your production application. The preview environment must also be configured to use the same API keys as your production environment.

Generally, hosts have a special feature to host the preview environment on a subdomain of your root domain, for example:

• Vercel: use the Preview Deployment Suffix feature. This feature is only available on Vercel's Pro and Enterprise plans.
• Netlify: use the Automatic Deploy Subdomain feature.

Using independent settings and user data

There are two approaches to creating a preview environment with independent settings and user data:

1. Easiest: Use your host's provided preview domain, like *.vercel.app or *.netlify.app, with development API keys from Clerk.
2. Acquire an additional root domain for your preview environment, completely separate from your production application's root domain.

Use your host's provided preview domain

Configure the preview environment to use development API keys from Clerk. It is currently not possible to use Clerk production API keys with your host's provided preview domain.

Acquire an additional root domain

To use an additional root domain, you must first configure your host to deploy preview environments to that domain:

• Vercel: use the Preview Deployment Suffix feature. This feature is only available on Vercel's Pro and Enterprise plans.
• Netlify: use the Automatic Deploy Subdomain feature.

You can configure this environment with either your development API keys (recommended) or you can create an additional production instance and use those production API keys.