Deploying a Clerk app to Vercel
Deploying a Clerk app to a Vercel project enables you to rapidly develop your applications and deploy them to production with ease.
Let's walk through the following:
- How to set up a new Vercel project
- How to integrate Clerk into your Vercel project
- Supporting Vercel Preview URLs in your Clerk app
Set up a new Vercel project
This guide assumes that you have already set up a Clerk application that you're ready to deploy. If you haven't yet, be sure to check out our guide to creating a new Clerk app.
To set up a new Vercel project, start by going to your Vercel Dashboard. Here, you'll see a list of your projects or, if you don't have any projects yet, a prompt to create a new project:
Create a new project by pressing the Add New button in the top right corner of the screen or by pressing this link:
Once done, you'll see the option to import a Git repository. Find the repository you want to use and press Import:
Once you've selected a project to deploy, you'll be directed to the Configure Project page.
On this page, make sure to add Environment Variables from your app's Clerk dashboard so that your Vercel project will be connected to your Clerk app properly:
The API keys added on this screen will be assigned to all deployments on Vercel, including preview URLs. To connect your first deployment to your Clerk app, be sure to use your Clerk production API keys rather than your development API keys.
Once you press Deploy, your app will deploy to production!
You will likely want to assign a custom domain to your Vercel project once you've completed this step.
Add Clerk API keys to existing Vercel project
To add your Clerk API keys to an existing Vercel project, start by selecting your project from your Vercel dashboard:
On the details page for your project, go to Settings in the navigation bar at the top:
In the Settings sidebar, select Environment Variables and add your API keys from your Clerk dashboard:
When adding Environment Variables, you can select which keys associate with which Vercel deployment Environments.
Using this, you can have your Production Vercel environment use your production Clerk API keys while keeping your preview and development Vercel deployments using your development Clerk API keys.
Support for Vercel preview URLs
Vercel provides a method for easily deploying preview URLs for development environments like GitHub PRs. An example of this preview functionality might look something like this:
If you're using your Clerk development key for this Vercel preview deployment, everything will work out-of-the-box.
We use Clerk magic to automatically detect the domain you're hosting from and handle redirects for you! ✨
However, if you wish to use your production Clerk keys with a preview Vercel deployment, you'll need to utilize Vercel's preview deployment suffix customization to host preview URLs under your primary domain's subdomain.
This is done to ensure your users' security by restricting production redirects to fall under your production domain. This prevents bad actors from maliciously requesting sign-in access to their own domains.
We take security very seriously at Clerk. To learn more about how Clerk ensures your user's security, please refer to our docs on the subject.
Please note that modifying the Preview Deployment Suffix is only available as an add-on to Vercel's Pro plans and above.
See the docs on preview environments to learn more.
Feedback
Last updated on