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.
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:
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:
export VERCEL_API_TOKEN=yourAPITokenValue
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:
npx create-next-app nextjs-terraform-demo
Before configuring Terraform, first push your Next.js app into GitHub.
nextjs-terraform-demo
.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.
mkdir terraform-example
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:
terraform {
required_providers {
vercel = {
source = "vercel/vercel"
version = "~> 0.3"
}
}
}
Run the following in the command line to initialize the project using main.tf
:
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):
resource "vercel_project" "example" {
name = "terraform-test-project"
framework = "nextjs"
git_repository = {
type = "github"
repo = "<username>/nextjs-terraform-demo"
}
}
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.
resource "vercel_project" "example" {
...
team_id = "<myteamid>"
...
}
Run the following in the command line to apply these changes:
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
:
│ Error: Error creating project
│
│ with vercel_project.example,
│ on main.tf line 10, in resource "vercel_project" "example":
│ 10: resource "vercel_project" "example" {
│
│ 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.
View a new Project created with Terraform Vercel provider.
You can now create a Deployment by committing Git changes and pushing them to the nextjs-terraform-demo
GitHub repository.
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:
data "vercel_project_directory" "example" {
path = "../nextjs-terraform-demo"
}
resource "vercel_deployment" "example" {
project_id = vercel_project.example.id
files = data.vercel_project_directory.example.files
path_prefix = "../nextjs-terraform-demo"
production = true
}
Inside the terraform-example
directory, run the following in the command line to review the changes that will be made:
terraform plan
The plan
command will output the files to be uploaded (inside the nextjs-terraform-demo
directory) and any additional settings such as production=true
.
Run the following in the command line to apply the changes:
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.
A successful deployment to Vercel with Terraform.
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:
resource "vercel_project_domain" "example" {
project_id = vercel_project.example.id
domain = "myproject-domain.vercel.app"
}
project_id
is taken from the definition of the vercel_project
resource. For example, since you defined the resource as resource "vercel_project" "example"
, the project_id
is vercel_project.example.id
Run the following command to confirm and then apply the changes:
terraform apply
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:
We will add more tutorials related to this in the future.
To learn more, please review the following links:
vercel_project
resources section for a list of options that you can use to configure your Vercel Project from Terraformvercel_deployment
resources example for an example Deployment configurationvercel_project_domain
resources example for an example domain configuration