# How can I use CircleCI with Vercel?

**Author:** Lee Robinson

---

You can use Vercel with CircleCI as your CI/CD provider to generate [Preview Deployments](https://vercel.com/docs/concepts/deployments/preview-deployments) for every `**git**` push and deploy to Production when code is merged into the `**main**` branch.

This approach is useful for developers who want full control over their CI/CD pipeline, or those who can't leverage Vercel's built-in [git integration](https://vercel.com/docs/concepts/git/vercel-for-github). This guide will help you get started using CircleCI with Vercel.

## Building Your Application

You can build your application locally (or in CircleCI) without giving Vercel access to the source code through `**vercel build**`. Vercel automatically detects your frontend framework and generates a `**.vercel/output**` folder conforming to the [Build Output API specification](https://vercel.com/docs/build-output-api/v3).

`**vercel build**` allows you to build your project within your own CI setup, whether it be CircleCI or your own in-house CI, and upload _only_ those build artifacts (and not the source code) to Vercel to create a deployment.

## Configuring CircleCI for Vercel

`**vercel deploy --prebuilt**` skips the build step on Vercel and uploads the previously generated `**.vercel/output**` folder from CircleCI. Let's define our jobs in `**.circleci/config.yml**`:

`version: 2.1 jobs: preview_deployment: docker: - image: circleci/node:latest environment: VERCEL_ORG_ID: $VERCEL_ORG_ID VERCEL_PROJECT_ID: $VERCEL_PROJECT_ID steps: - checkout - run: name: Install Vercel CLI command: npm install --global vercel@latest - run: name: Pull Vercel Environment Information command: vercel pull --yes --environment=preview --token=$VERCEL_TOKEN - run: name: Build Project Artifacts command: vercel build --token=$VERCEL_TOKEN - run: name: Deploy Project Artifacts to Vercel command: vercel deploy --prebuilt --token=$VERCEL_TOKEN production_deployment: docker: - image: circleci/node:latest environment: VERCEL_ORG_ID: $VERCEL_ORG_ID VERCEL_PROJECT_ID: $VERCEL_PROJECT_ID steps: - checkout - run: name: Install Vercel CLI command: npm install --global vercel@latest - run: name: Pull Vercel Environment Information command: vercel pull --yes --environment=production --token=$VERCEL_TOKEN - run: name: Build Project Artifacts command: vercel build --prod --token=$VERCEL_TOKEN - run: name: Deploy Project Artifacts to Vercel command: vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN workflows: version: 2 preview_and_production: jobs: - preview_deployment: filters: branches: ignore: /main/ - production_deployment: filters: branches: only: /main/`

The `**preview_deployment**` job will run when your code is pushed to a git branch other than `**main**`, and the `**production_deployment**` job will run when code is merged into the `**main**` branch.

Next, add the required values from Vercel as environment variables in CircleCI:

1. Retrieve your [Vercel Access Token](https://vercel.com/guides/how-do-i-use-a-vercel-api-access-token)
   
2. Install the [Vercel CLI](https://vercel.com/cli) and run `**vercel login**`
   
3. Inside your folder, run `**vercel link**`to create a new Vercel project
   
4. Inside the generated `**.vercel**`folder, save the `**projectId**` and `**orgId**` from the  `**project.json**`
   
5. In CircleCI, add `**VERCEL_TOKEN**`, `**VERCEL_ORG_ID**`, and `**VERCEL_PROJECT_ID**` as [Environment Variables](https://circleci.com/docs/guides/security/set-environment-variable/)
   

## Deploying Your Vercel Application with CircleCI

Now that your Vercel application is configured with CircleCI, you can try out the workflow:

- Create a new pull request to your repository
  
- CircleCI will recognize the change and use the Vercel CLI to build your application
  
- The job uploads the build output to Vercel and creates a Preview Deployment
  
- When the pull request is merged, a Production build is created and deployed
  

Every pull request will now automatically have a Preview Deployment attached. If the pull request needs to be rolled back, you can revert and merge the PR and Vercel will start a new Production build back to the old git state.

---

[View full KB sitemap](/kb/sitemap.md)