āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/development/managing-environments ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
When creating a new application within Clerk, you are provided with two instances: Development and Production. These instances vary slightly and should only be used appropriately.
A Development instance is Clerk's default instance type and has characteristics that allow it to be more useful for local development. To facilitate development and local authentication, Development instances have a more relaxed security posture and are not suitable for production workloads.
Some notable examples of Development-only characteristics in a Clerk application are:
Development banner is shown prominently in the Clerk Dashboard to make clear you're managing or configuring non-production data.Development instances for production purposes.accounts.dev instead of your app's production domain.accounts.dev instead of your production domain.localhost and <slug>.accounts.dev. The __clerk_db_jwt object is only used in development environments. For more specific details on the differences between Clerk's session management architecture in development and production environments, see the technical breakdown below.[!NOTE] All paid functionality is available in a
Developmentinstance. However, when you deploy your application toProduction, you will be asked to upgrade to aProaccount if you are using paid features. See our pricing page for full details.
A Production instance is the more robust option of Clerk's instance types. Production instances are meant to support high volumes of traffic and by default, have a more strict security posture.
Some notable differences between Production and Development instances in a Clerk application are:
When deploying to production, you must first activate your Production environment. See the Deploying to Production guide to learn about the process and avoid common pitfalls.
Staging environments enable you to internally test and demo changes to your application or website before deploying them to production. Currently, Clerk only offers Development and Production instances. Official support for Staging instances is still on the roadmap. However, you can set up a "staging environment" by creating a separate Clerk application with a separate domain.
Creating a separate Clerk application will prevent you from using live production environment data in your staging environment. If you are on a Pro, Enterprise, or Startup plan, Clerk will fully upgrade your staging application for free.
It is important to note that when you use a separate Clerk application for your staging environment, changes to this application will not be automatically mirrored in your main application for your production environment. You must manually make these changes yourself if you want them to be reflected in both applications.
The following steps will help you set up a new Clerk application with a staging-specific domain:
my-site.com, you could use staging.my-site.com.While staging environments are typically long-lived, preview environments are typically generated on-demand for specific pull requests. See the section on using Clerk in a preview environment to learn about your options.
If you would like to share settings and data between your production and staging environments, see the dedicated guide. This is not recommended because you will be sharing a user table between your production and staging environments.
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:
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:
There are two approaches to creating a preview environment with independent settings and user data:
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.
[!WARNING] To use an independent environment, it is critical that you acquire an additional domain. An independent environment will not work if it is configured on the same domain as your production application, even if it is on a separate subdomain.
To use an additional root domain, you must first configure your host to deploy preview environments to that domain:
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.
[!TIP] In order to understand this section, it's recommended to have a solid understanding of how Clerk's session management architecture works. For more information on this topic, check out the guide on how Clerk works.
Clerk manages session state differently in production and development environments.
<Include src="_partials/clerkdbjwt-vs-client-cookie" />ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā