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(opens in a new tab). 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:

A Vercel dashboard with a "No projects, yet!" message. Buttons to create a new project and browse templates are present.

Create a new project by pressing the Add New button in the top right corner of the screen or by pressing this link(opens in a new tab):

The top right corner shows an "Add New" dropdown. Press the "Project" item in the dropdown

Once done, you'll see the option to import a Git repository. Find the repository you want to use and press Import:

An "Import Git Repository" screen provides a few options, including selecting an organization and list of related repositories to 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(opens in a new tab) from your app's Clerk dashboard(opens in a new tab) so that your Vercel project will be connected to your Clerk app properly:

The "Configure Project" page allows you to add environment variables, select a framework preset, and more

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.

You'll need to take additional steps to make sure Vercel preview URLs work as intended.

Once you press Deploy, your app will deploy to production!

You will likely want to assign a custom domain to your Vercel project(opens in a new tab) 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(opens in a new tab):

A card for the "clerk-nextjs-starter" project on our Vercel dashboard

On the details page for your project, go to Settings in the navigation bar at the top:

When you open a project, there's a list of navigation items at the top. At the end of these items is "Settings"

In the Settings sidebar, select Environment Variables and add your API keys from your Clerk dashboard(opens in a new tab):

In the project settings for a Vercel project, there's a list of settings. Four items from the bottom is "Environment Variables"

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.(opens in a new tab) An example of this preview functionality might look something like this:

A comment on a GitHub pull request from the Vercel bot showing a preview link of your project

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 deploment suffix customization(opens in a new tab) 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.

Last updated on April 17, 2024