Docs

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

Note

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:

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:

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 from your app's Clerk dashboard 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.

Note

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!

Note

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:

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:

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. 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.

Note

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.

Note

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.

Note

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

What did you think of this content?
Edit this page on GitHub