Integrating Terraform with Vercel

Terraform is an infrastructure as code (IaC) driven software that allows you to programmatically configure your project infrastructure using configuration files and version control. This mode of allocation ensures logical management and monitoring of resources such as servers, networks, and cloud storage instead of a manual operation for each required resource.

These infrastructure configurations are handled via a JSON-like configuration language called HCL (HashiCorp Configuration Language). For example, when you deploy a project, run a server, and manage your GitHub org or SAML provider, Terraform parses your code and translates it to an API call to the resource provider.

This guide will teach you how to use the Vercel integration with Terraform.

About the Integration

Using the Terraform Vercel provider, you can integrate Vercel with the other third-party services and handle complex preview environment setups that use Vercel for the front-end and other back-end services.

The Vercel Terraform provider is open-source, and you can access it from the Terraform registry. It allows developers to:

• Create and configure projects
• Create Vercel deployments
• Configure domains for Vercel projects

In addition, the Terraform Provider facilitates using Vercel alongside a range of other third-party services, such as Google Cloud Platform (GCP), Amazon Web Services (AWS), Fastly or Cloudflare.

This integration is helpful for two groups:

• Developers that use Terraform to manage their infrastructure and are looking to use Vercel
• Developers that combine multiple third-party services to power their applications

Set up Terraform

• First, install the Terraform CLI. Follow this guide that explains how to do this for all operating systems
• Next, connect Terraform to your Vercel account. This is possible via creating an access token that interacts with your account. Follow this guide to create an access token in the Vercel dashboard. This tutorial will create resources underneath your Personal account, which requires the ‘Full Access’ scope. The token name can be anything you want - however, it's recommended to use ‘terraform’.
• Finally, add the access token as a shell environment variable by running the following in the command line:

1
export VERCEL_API_TOKEN=yourAPITokenValue

Create and configure a Project

Let's start with a basic Next.js application, which you can configure using Terraform.

To create a Next.js app, open your terminal, cd into the directory you’d like to create the app in, and run the following command:

1
npx create-next-app nextjs-terraform-demo

Before configuring Terraform, first push your Next.js app into GitHub.

• On your personal GitHub account, create a new repository called nextjs-terraform-demo.
• The repository can be public or private. You do not need to initialize it with a README or other files.
• If you need help setting up your repo, take a look at this guide on GitHub.

Then push the Next.js app to your GitHub repository.

Once your GitHub repo is live, you can configure a Vercel Project to use this repository via Terraform.

Alongside your nextjs-terraform-demo directory, create a folder for your Terraform code.

1
mkdir terraform-example
2
cd terraform-example

Then, you need to create a Terraform file in your project folder and add Vercel as a provider.

Create a file called main.tf and paste the following content:

1
terraform {
2
  required_providers {
3
    vercel = {
4
      source = "vercel/vercel"
5
      version = "~> 0.3"
6
    }
7
  }
8
}

Run the following in the command line to initialize the project using main.tf:

1
terraform init

Now that Vercel is initialized as a provider, you can create a Vercel Project for your project without leaving the command line.

Edit the main.tf file and add the following content (replace <username> with your GitHub username):

1
resource "vercel_project" "example" {
2
  name      = "terraform-test-project"
3
  framework = "nextjs"
4
  git_repository = {
5
    type = "github"
6
    repo = "<username>/nextjs-terraform-demo"
7
  }
8
}

If you wish to create the Project inside a team account instead, specify the team_id as follows in the resource definition. You can find your team_id under the Settings tab of your team account.

1
resource "vercel_project" "example" {
2
  ...
3
  team_id = "<myteamid>"
4
  ...
5
}

Run the following in the command line to apply these changes:

1
terraform apply

You will be asked for a confirmation prompt where only typing yes will continue the process. This command takes only a few seconds, and you will receive a confirmation once it's complete.

Note, you need to have the Vercel GitHub App installed. If this is not the case, you get an error message upon running terraform apply:

1
│ Error: Error creating project
2
│
3
│   with vercel_project.example,
4
│   on main.tf line 10, in resource "vercel_project" "example":
5
│   10: resource "vercel_project" "example" {
6
│
7
│ Could not create project, unexpected error: bad_request - To link a GitHub repository, you need to install the GitHub integration first.

You can now check your Vercel dashboard for the account where you added the integration. You should see a project called terraform-test-project added. If you go inside the project and look under the Git settings, you will find that your GitHub repository is connected to the Project.

You can now create a Deployment by committing Git changes and pushing them to the nextjs-terraform-demo GitHub repository.

Deploy directly through Terraform

You have created a project using the GitHub integration with a Terraform configuration. You can also deploy directly with Terraform without using the Vercel GitHub integration.

Return to your main.tf inside the terraform-example directory and add the following content:

1
data "vercel_project_directory" "example" {
2
  path = "../nextjs-terraform-demo"
3
}
4

5
resource "vercel_deployment" "example" {
6
  project_id  = vercel_project.example.id
7
  files       = data.vercel_project_directory.example.files
8
  path_prefix = "../nextjs-terraform-demo"
9
  production  = true
10
}

Inside the terraform-example directory, run the following in the command line to review the changes that will be made:

1
terraform plan

Run the following in the command line to apply the changes:

1
terraform apply

You will see the progress of the Deployment creation and build in the command line as the Project is deployed. When the Deployment is ready, the progress output will stop, show that the apply command is complete and return to the command line. If you check your Vercel Project's Deployments page, you will see a new Deployment with a create-next-app output.

If you make any changes in your nextjs-terraform-demo directory, go back to the terraform-example directory and run terraform apply, a new Deployment will automatically be created based on those changes.

Configure Vercel Project domains

After configuring your Terraform to create Deployments, let's look at how you can configure a vercel.app domain or a custom domain with your Vercel Project via Terraform.

Edit your terraform-example/main.tf file and add the following:

1
resource "vercel_project_domain" "example" {
2
  project_id = vercel_project.example.id
3
  domain     = "myproject-domain.vercel.app"
4
}
5

Run the following command to confirm and then apply the changes:

1
terraform apply

Additional applications

You can also use Terraform to integrate third-party services like Amazon Web Services (AWS) with your Vercel Project in a way that gives you additional flexibility, such as:

• Being able to set all the configuration of the AWS services you are using inside a Terraform configuration file inside your Project directory
• Being able to pass values generated by an AWS service to a Vercel Deployment via an environment variable.

We will add more tutorials related to this in the future.

That's It!

To learn more, please review the following links:

• Terraform vercel_project resources section for a list of options that you can use to configure your Vercel Project from Terraform
• Terraform vercel_deployment resources example for an example Deployment configuration
• Terraform vercel_project_domain resources example for an example domain configuration
• Additionally, Terraform published a useful guide to creating preview environments with Terraform, GitHub Actions, and Vercel.